Writing Docs
#
Add a Markdown FileTo add a page to the docs create a markdown file in the docs
directory (or a subdirectory of docs
if necessary).
Docs should use .md
as the extension unless you are using MDX - which for a normal doc is usually not the case. You can always rename docs later if you decide to add MDX.
#
Document HeaderEvery doc file needs a header - this means it starts with a simple block of text with some configuration options.
This example should be sufficient for most docs, but a full list of options can be found here.
The id
needs to be something unique - check that the id you plan to use hasn't already been used by looking in sidebars.js
.
The title
is displayed as the first heading on a docs page.
The sidebar_label
is what is shown in the navigation sidebar for the doc. It is a good idea to have something short here, and have the title
as something slightly longer if needed.
#
Adding to The SidebarUsually you will want your document to be accessible through the navigation sidebar. If you look at sidebars.js
you will see the current categories. Try to put your doc into one of these categories as this keeps the sidebar clean. If you think a new category is needed, take a look at the sidebar docs for guidance.
#
Adding ContentNow you are ready to add the content of your new doc page! Have a look at the docusaurus docs for markdown features for hints on formatting the doc.
This page might also be useful if you plan to use static assets such as images in your doc.
#
VersioningWe are using versioning for this site as Netkit-JH is being frequently updated, and lots of docs are specific to a Netkit-JH release.
Normally you should just add to the docs
directory as this is the Next
version - the default version that will be shown to site visitors.
Anything that is put in the docs
directory will be frozen as the next release, when that point is reached. For example, if the latest release is 1.0.0
and the next release is 1.0.1
, then everything currently in docs
will be frozen as version 1.0.1
, when the release happens.
If you want to make a doc specific to a particular release then place it in versioned_docs/VERSION
.
Example:
Say the latest release was 1.0.0
and the next release is 1.0.1
.
You are writing a doc that is relevant to 1.0.0
, but you know it will no longer apply in 1.0.1
.
You should put this doc in the versioned_docs/version-1.0.0/
directory.