Skip to content

Latest commit

 

History

History
16 lines (12 loc) · 2.14 KB

README.md

File metadata and controls

16 lines (12 loc) · 2.14 KB

Docs instructions

Note that if you are creating a library or framework, you may want to include documentations. You can use an external framework like mkdocs or readthedocs.io, or include it here.

Jekyll is designed to host docs very well with a lot of options for customization, but it's a bit difficult to get started. You will need to know about the following files:

  • /docs/_config.yml: This is the config for the entire webpage. In there, you will find specific settings:
    • include: As you can notice, we can find "_docs" there. This means that the relative path _docs is included, which resolves to /docs/_docs. Note we could've called it _foobar if we wanted, it doesn't really matter, but we used _ as a convention.
    • defaults: This variable scopes the path "_docs" (again, relative to _config.yml) that we defined in include. It specifies important default values, such as the left sidebar that include a list of pages, and the right sidebar that includes a table of content, or toc as abbreviated. You can override those values by specifying in the front matter of a page, e.g. you can edit ./_docs/api.md and rename by setting toc_label: "new name". Notice also that nav: sidebars-docs, this references the navigation layout explained below.
  • /docs/_data/navigation.yml: This controls any navigation in your page, including the navigation sidebar on the left side. You can find a variable sidebar-docs, which specifies the layout of the
  • /docs/_docs: This contains all doc-related pages. Any markdown file placed here will automatically receive the defaults specified in _config.yml. The name of the files do not matter, as the title and the relative URL are specified in the front matter. For example, we have _docs/home.md which we have specified to redirect to /docs/, but we could've chosen /foo/bar if we wanted.

Read more about navigation sidebars here:

Read more about table of contents here: https://mmistakes.github.io/minimal-mistakes/layout-table-of-contents-post/