Layout
The layout of your docs folder is the navigation.
docs/
README.md the first page
logo.svg optional, the logo in the header
favicon.svg optional, or favicon.png or favicon.ico
style.css optional, your styles
template.templ optional, your template, as any .templ file
1-get-started/ a group, "Get started"
icon.svg optional, the icon of the group
1-installation.md a page, at get-started/installation
2-upgrading.md a page, at get-started/upgrading
2-tutorial/
README.md opens the group, at tutorial/
1-create-project.md a page, at tutorial/create-project
icons/ other files, such as icons
versions/ fixes of your releases
Groups and pages
- A folder whose name starts with a number and
-is a group. The number sets its place, and the rest of the name is its title:1-get-startedbecomes "Get started". - A Markdown file in a group whose name starts with a number and
-is a page. Leading zeros, as in01-intro.md, keep file listings in the same order. - The
README.mdof a group opens the group. - The
README.mdof the docs folder is the first page of the site and the first entry of the first group.
The numbers stay out of URLs and titles. The title of a page is the text of its level 1 heading, unless its front matter sets title.
What fails the build
- A Markdown file in a group without a number, other than
README.md - 2 entries with the same number
- A group inside a group
- A group without pages, or a docs folder without groups
Other files
The navigation leaves out folders without a number, such as icons/. Keep the files there that your pages and settings link to. versions/ holds the fixes of your releases.
Icons
logo.svg, the icon.svg of a group and every other icon go into the page as inline SVG. Draw them with currentColor and they take the color of the text in both themes, as the icon of this group beside "Guide" in the navigation:
docs/2-guide/icon.svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<path d="M3 5.5C5.5 4 8.5 4 12 6c3.5-2 6.5-2 9-.5v13c-2.5-1.5-5.5-1.5-9 .5-3.5-2-6.5-2-9-.5zM12 6v13"/>
</svg>