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.
Go to your clone of the
If you already have an
adaptrepo, change to the root directory of that repo.
If you don't already have one, clone it like this:
git clone firstname.lastname@example.org:unboundedsystems/adapt.git cd adapt
Do an initial build of the docs website
This command will:
- Clone the
adapt-webrepo, placing it in the
websubdirectory of your
- Do a complete build of
adaptand its libraries, including generating documentation from the source code.
- Copy all the latest versions of documentation from
- Install and build everything within the
- 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.
All documentation should be authored within the
adaptsource code repo. Do not edit documentation directly in the
adapt/webdirectory, which is a separate repo.
API documentation is written in TSDoc format in the source code. All other documentation goes in the
Make changes to
.mdfiles in the
adapt/docsdirectory or to TSDoc comments in source code files.
Generate updated documentation and copy to
This command builds the documentation from the Adapt repo and copies it into the
adapt-webrepo, which is in the
The local preview server should notice the changed files and update with the new content.
The docusaurus live reload local server seems to have trouble updating with certain types of changes, primarily when there are changes in the
websitedirectory. If you don't see the changes you expect, try killing (
Ctrl-C) the local server and run
make previewagain in the
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
All markdown docs should have a YAML-based front matter header that contains at least
id: mydoc title: My Document
Embedded HTML is permitted, where required.
## This title has <span class="special">extra formatting</span>!
Images and other assets go in
To keep them organized, please place them in a subdirectory within
docs/assetsthat matches the relative path to the markdown file within
For more info, see the Docusaurus docs.
adapt-web repo structure
The interesting directories in the repo are:
|docs||Contains all of the versioned documentation content (Markdown and associated assets). Docs authored & generated in the |
|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.|