Structuring the docs

The directory structure of a docs site will look something like:

\-- docs
    |-- index.md
    \-- sub_dir
        |-- index.md
        |-- another_page.md
    \-- _data
        |-- site.yml
    \-- _files
        |-- some_file.pdf
    \-- _images
        |-- some_image.png

Directory structure

The starter kit assumes the following:

All published docs live in a docs directory. There should be an index file in this directory that will be the homepage to the site. This is usually called index.md, but other types of file can be used if you want to customise the homepage. For exmaple, a Nunjucks tempate called index.njk could be used.

Doc pages can be organised in subdirectories inside the docs directory. Ideally there should only be one level of nesting, but deeper nesting can be used if desired; although the theme doesn't currently handle these very well.

All subdirectories should contain an index file (e.g. index.md). If this is missing an error will be thrown and the docs won't complile.

Generally your content should be a collection of Markdown pages in the docs directory, but as the starter kit uses 11ty it's possible to use other types of files.

Data directory

There should be a file in a docs/_data/ directory called site.yml which is used to set global configuraton. See the metadata page for more information on what this file should contain.

Image handling

Images in markdown files

Images in markdown files should be added to the docs/_images directory and linked in the markdown file as a relative link to the image. For example: ![Image description](_images/my-image.png).

There is no need to optimise these images before hand. Images in referenced in Markdown are processed by the 11ty image plugin to create responsive images in a variety of image formats and the markup for these added to the generated HTML.

Images in the theme

Images in the theme should be placed in docs/_assets/images. These are copied to dist/_assets/images at compile time and so they should be optimised for the web beforehand.

File handling

Files can be added to the docs/_files directory which are then copied as is to the dist/_files directory at compile time. Links to files in Markdown should be absolute links to the file in the /_files/ directory. For exmaple /_files/my-file.pdf.

Last updated: