Organization of repositories
Git is an open-source version control system. The files are stored in repositories. GitHub is a web-based hosting service for Git repositories.
File names and file extensions
- Use a descriptive name based on the top-level heading in the file.
- Use single hyphens as word separators. Don't use underscores or camel-case.
- Use lower-case letters, numbers, and dashes only.
- Omit articles and the word and.
- <feature/context>-nav.md or index.md (for landing pages)
If there are multiple features or contexts in a single folder, you need to specify that in the file names. Otherwise, the parent folder should make that clear.
We use sub-folders to group similar content, images, and reusable snippets. The organization on GitHub only loosely resembles the structure on
At the root of the repo, there is a folder named docs. In it, you can find general pages that relate to the overall website and a set of sub-folders that match the features/APIs or common scenarios.
All major folders have a /media subfolder for the corresponding media files.
All major folders have a /includes subfolder for reusable content in that section. See Markdown reference for how to use includes.
Markdown file template
We use the Blueprint extension for Visual Studio Code. Available templates are located in the blueprint-templates folder at the root of the repo.