Context
Files and directories under docs/ mix naming styles, which makes paths unpredictable and links easy to get wrong:
- Concatenated PascalCase:
Contributing.md, Documentation.md, GitHubFlow.md, LocalDevelopment.md, RunningTests.md, MigrateElogData.md, PythonSDK.md, RestAPI.md, Dashboard.md, Logbook.md, Login.md, Sharing.md, SmartphoneUsage.md
- Underscore:
Data_Model.md, Step_by_Step_Setup.md, Step_by_Step_Setup_Docker.md, Step_by_Step_Setup_Kubernetes.md
- Capitalized directories:
Development/, Ingestor/, Operator/, Users/
- Underscore assets:
assets/scilog_logo.png, assets/scilog_poster.pdf, assets/scilog_poster.pptx
Proposed convention
Files and directories under docs/ use kebab-case: lowercase ASCII letters and digits, words separated by single hyphens (-); no uppercase, underscores, or spaces. Applies to Markdown pages, directories, and assets.
Why kebab-case
These paths are published as documentation URLs (HonKit builds docs/ to the gh-pages site). Kebab-case is the conventional choice for URLs: lowercase avoids case-sensitivity mismatches between local filesystems and web servers (a link that resolves locally can 404 when served), and hyphens are the standard word separator in URLs — more readable and linkable than underscores or percent-encoded spaces.
Exceptions
SUMMARY.md and the section-index README.md files are HonKit's summary/readme files. Per the HonKit configuration docs these default to SUMMARY.md/README.md, are configurable via book.json (structure.summary/structure.readme), and must sit at the book root. book.json, package.json, and package-lock.json are tooling config with tool-fixed names.
Context
Files and directories under
docs/mix naming styles, which makes paths unpredictable and links easy to get wrong:Contributing.md,Documentation.md,GitHubFlow.md,LocalDevelopment.md,RunningTests.md,MigrateElogData.md,PythonSDK.md,RestAPI.md,Dashboard.md,Logbook.md,Login.md,Sharing.md,SmartphoneUsage.mdData_Model.md,Step_by_Step_Setup.md,Step_by_Step_Setup_Docker.md,Step_by_Step_Setup_Kubernetes.mdDevelopment/,Ingestor/,Operator/,Users/assets/scilog_logo.png,assets/scilog_poster.pdf,assets/scilog_poster.pptxProposed convention
Files and directories under
docs/use kebab-case: lowercase ASCII letters and digits, words separated by single hyphens (-); no uppercase, underscores, or spaces. Applies to Markdown pages, directories, and assets.Why kebab-case
These paths are published as documentation URLs (HonKit builds
docs/to the gh-pages site). Kebab-case is the conventional choice for URLs: lowercase avoids case-sensitivity mismatches between local filesystems and web servers (a link that resolves locally can 404 when served), and hyphens are the standard word separator in URLs — more readable and linkable than underscores or percent-encoded spaces.Exceptions
SUMMARY.mdand the section-indexREADME.mdfiles are HonKit's summary/readme files. Per the HonKit configuration docs these default toSUMMARY.md/README.md, are configurable viabook.json(structure.summary/structure.readme), and must sit at the book root.book.json,package.json, andpackage-lock.jsonare tooling config with tool-fixed names.