Adapt Developer: Writing Docs
Overview
Adapt documentation source content is stored alongside the Adapt source code in the adapt
repo, primarily in Markdown files.
Those source Markdown files, along with automatically generated API documentation files, are pushed to the adapt-web
repo for publishing.
The adapt-web
repo uses Docusaurus v1 to transform the source Markdown files into a React-based website, which is then hosted by Netlify at https://adaptjs.org.
Setting up
Go to your clone of the
adapt
repoIf you already have an
adapt
repo, change to the root directory of that repo.If you don't already have one, clone it like this:
git clone git@gitlab.com:unboundedsystems/adapt.git cd adapt
Do an initial build of the docs website
make web-build
This command will:
- Clone the
adapt-web
repo, placing it in theweb
subdirectory of youradapt
repo. - Do a complete build of
adapt
and its libraries, including generating documentation from the source code. - Copy all the latest versions of documentation from
adapt
into theweb/docs
directory. - Install and build everything within the
web
directory.
- Clone the
Run the local preview server
cd web make preview
This will start a local preview server (in a Docker container) in watch mode that serves the documentation website from your repo. You can point your browser to http://localhost:3000 to see the local preview site. As you change the docs (see Authoring workflow below), the changes should be reflected in the local site so you can preview them.
Authoring workflow
Reminder
All documentation should be authored within the adapt
source code repo.
Do not edit documentation directly in the adapt/web
directory, which is a separate repo.
API documentation is written in TSDoc format in the source code.
All other documentation goes in the adapt/docs
directory.
Make changes to
.md
files in theadapt/docs
directory or to TSDoc comments in source code files.Generate updated documentation and copy to
adapt/web/docs
make web-docs
This command builds the documentation from the Adapt repo and copies it into the
adapt-web
repo, which is in theadapt/web
directory.The local preview server should notice the changed files and update with the new content.
tip
The docusaurus live reload local server seems to have trouble updating with certain types of changes, primarily when there are changes in the website
directory.
If you don't see the changes you expect, try killing (Ctrl-C
) the local server and run make preview
again in the adapt/web
directory.
Source code comments
- Source code is documented using TSDoc format, implemented by API Extractor. So their reference guide for writing comments is the best one to use.
- A subset of Markdown is supported within source code comments, but formatting isn't always the greatest. Use the local preview server to see how your comments will format in the user documentation.
Markdown document tips
Docusaurus uses GitHub flavored markdown, as implemented by the Remarkable markdown parser.
All markdown docs should have a YAML-based front matter header that contains at least
id
andtitle
.Example:
--- id: mydoc title: My Document ---
Embedded HTML is permitted, where required.
Example:
## This title has <span class="special">extra formatting</span>!
Callouts are supported through the
remarkable-admonitions
Remarkable pluginExample:
:::warning This is a warning :::
Supported callout types are:
tip
note
important
caution
warning
Images and other assets go in
docs/assets
To keep them organized, please place them in a subdirectory within
docs/assets
that matches the relative path to the markdown file withindocs
.For more info, see the Docusaurus docs.
adapt-web repo structure
The interesting directories in the repo are:
Directory | Content |
---|---|
docs | Contains all of the versioned documentation content (Markdown and associated assets). Docs authored & generated in the adapt repo get copied here. |
website | Node.js project directory that contains the Docusaurus configuration and React components, along with static assets from which the website is built. |
adapt-web-components | A React components library, specific to this site. |