The docpad-skeleton-apidoc repository is a simple documentation portal theme/template. It is based on a static site generator called DocPad. It is also, by default, configured to use Chewie, the module supporting distributed source publishing.
Go through this tutorial to:
- Set up your local environment to build a documentation portal
- Understand and configure your own distributed source publishing flow
- Publish the portal to GitHub Pages
You will use the following technologies:
- Git and GitHub and GitHub Pages
- DocPad and the documentation portal template based on it: docpad-skeleton-apidoc
- Chewie, a distributed source publishing tool
Git is a source control management system for any type of text file. It allows you to keep several versions of a file and merge them into one file at any time.
You can group sets of files in so-called repositories.
The most widely-known tools are:
- Git CLI
- GitHub Desktop
- SourceTree
GitHub is a Git hosting service and much more, including:
- Project management
- Issue reporting
- Wiki
The best-known alternative is Bitbucket.
GitHub Pages provides free static site hosting, integrated with GitHub.
The best-known alternative is GitLab Pages.
DocPad is a static site generator and much more. By defining layouts, you can generate entire documentation portals with sources written in simple markdown syntax.
The most widely-known alternatives are:
- Jekyll and a template from Tom Johnson
- Sphinx, which is probably behind the Write the Docs community
See this list of known documentation sites templates based on static site generators: https://github.com/derberg/docs-with-static-site-generators
Markdown is a simple markup language used in plain text files. Later, you can convert such file into any other format, such as HTML. Sample usage includes this document and all other documents that describe this workshop.
The best known alternatives are:
Chewie makes it possible to distribute documentation content in different locations. It supports content registry management, independent document generation, and publishing.