Output formats

Modo🧯 generates Markdown files. These files need to be processed further to obtain an HTML site that can be served on GitHub Pages (or elsewhere). Modo🧯 supports different formats to make this step easier, via the config field format or flag --format.

Hugo

With format hugo, Modo🧯 creates a minimal Hugo project, and Markdown files with front matter and cross-references for Hugo. The generated files can be used by Hugo without any further steps:

modo init hugo      # required only once to set up the project
modo build
hugo serve -s docs/site/

When using the default structure obtained from modo init hugo, the Hugo project resides under docs/site. However, Hugo’s content folder docs/site/content is in .gitignore and only contains files generated by Modo🧯. All additional content files (like a user guide) should instead be placed under docs/src, as if this was the content folder. These files are processed for doc-tests. Besides that, the Hugo project can be used and modified as usual.

Templates can be used to customize the Hugo front matter of each page.

Hugo itself is extremely versatile and the provided setup is just a minimal suggestion that uses the Hextra theme. For a more customized documentation site (using Hextra as well), see the sources of this site.

mdBook

With format mdbook, Modo🧯 creates Markdown files as well as auxiliary files for mdBook. The generated files can be used by mdBook without any further steps:

modo init mdbook     # required only once to set up the project
modo build
mdbook serve docs/ --open

When using the default structure obtained from modo init mdbook, you can edit the mdBook configuration file book.toml under docs/

Note that the mdBook format is more limited than Hugo, as it allows only for a single package and no auxiliary documentation files.

Plain Markdown

With format plain, Modo🧯 creates plain markdown files. This is Modo🧯’s default output format. The generated files are suitable for pushing to GitHub and GitHub’s Markdown rendering.

When using the default structure obtained from modo init plain, Modo🧯’s generated files are placed under docs/site, which is in .gitignore. All additional content files (like a user guide) should be placed under docs/src. As with the Hugo format, these files are processed for doc-tests.