docs: document the per-platform custom library structure - #133
Open
gantoine wants to merge 3 commits into
Open
Conversation
Add a "Custom library structure" section to Folder Structure covering the template syntax, several templates per platform, relocation semantics and the gotchas, plus a `filesystem.structure` entry in the config reference. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Testing the feature against a live library showed RomM moves nothing when a platform's template is removed: the nested games are flagged missing and the folders that grouped them are picked up as multi-file games instead. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Matching a gamelist entry now keys on its path relative to the platform folder, falling back to a bare file name, and both exporters write paths (and media) that follow the structure. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Documents the per-platform custom library structure (
filesystem.structure) added in rommapp/romm#3571.Two pages change:
Custom library structuresection, between the visual reference of the default layouts and the naming convention: the template syntax, declaring several templates for one platform, what happens when games move within the structure, and the gotchas (hidden folders, grouping-level vs multi-file game, same-named files in different folders).filesystem.structureentry with a short example, linking to the section above for the full syntax.Live pages: https://docs.romm.app/latest/getting-started/folder-structure/ and https://docs.romm.app/latest/reference/configuration-file/
Why
The feature shipped with its whole reference living as a 45-line comment block in
config.example.yml, which is the wrong home for it: it is prose, it is not discoverable from the docs site, and the example config is meant to be skimmed. rommapp/romm#3571 now keeps only the syntax essentials plus the examples there, and links here, matching how thestreamingblock already points at its guide.Every claim on the new page was re-checked against the implementation rather than copied over from the comment. One note did not survive that check and is deliberately absent: the old comment said a move that also changes a game's size is not detected as a relocation, because a size pre-filter runs before hashing. That pre-pass was dropped during review of rommapp/romm#3571 (
mark_missing_romsnow runs before the identify loop, so every unmatched file reachesget_matching_missing_rom), and archives are hashed over their decompressed members, so compressing a game no longer breaks relocation. The page states the conditions that actually apply today: all three hashes must match, non-hashable platforms fall back to the title id read out of the binary, and an ambiguous identity imports as a new game.Verification
uv run mkdocs build --strictpassestrunk fmt/trunk checkclean on both files#custom-library-structure,#filesystemstructure) resolve in the built site, and are what feat: Per-platform custom library structure with non-destructive identity romm#3571 links toAI disclosure
Written with Claude Code, including the pass verifying each documented behavior against the backend source. I reviewed the result before submitting.
🤖 Generated with Claude Code