Skip to main content

FAQ

This section is meant to address and document common questions, mistakes, errors, and pitfalls that people might run into. Apart from being a template, it also contains actual frequently asked questions with regarding to performing documentation of AGIL Ops Hub with Docusaurus.

How should I name my folders and markdown files?​

All folder names and markdown files should be in kebab-case. Do not use numbers to order the folders in the folder-browser. Keep the name of the folder similar to the title of the text in the sidebar that it represents so other users can find the folder if they need to.

We don't use numbers to order them as it causes a lot of broken links when we attempt to do any re-ordering later.

Use the sidebar_order and sidebar_label front matter to control their position and label in the sidebar.

Where should I put my images?​

Store your images in the static/img/** folder. You should create folders that match where your docs are if have many images (usually as part of a tutorial or guide) that are meant to be in a specific section/module.

We don't co-locate the images in with the docs they are used as they sometimes need to be shared. We'll keep things simple by having them all in the static/img/** folder.

How should I name my images?​

Use kebab-case to name your images, give them a descriptive name as there will be many images in the docs, making it difficult for you to find your image if your image name and description is too general.

How should I show placeholder text in commands?​

We have a class called highlight in the Docusaurus custom.css file that is meant to be used to highlight placeholder text - that is text that the reader is meant to replace with their own values.

In order to be able to use this in code blocks, you can't use the usual triple backtick ``` syntax for code blocks, you should use the <CodeBlock> component instead - an example is given below:

Actual Code:

CodeBlock jsx
<CodeBlock language="bash">
	{`$ echo `}
	<span className="highlight">TOKEN</span>
	{` | docker login ghcr.io -u `}
	<span className="highlight">USERNAME</span>
	{` --password-stdin`}
</CodeBlock>

-   Replace <span className="highlight">TOKEN</span> with your token
-   Replace <span className="highlight">USERNAME</span> with your username

Render Output:

$ echo TOKEN | docker login ghcr.io -u USERNAME --password-stdin
  • Replace TOKEN with your token
  • Replace USERNAME with your username

Linking versioned docs to versioned docs​

This applies to all docs in docs/versioned:

Because we use Docusaurus' versioning system, all links that refer to other docs must use relative file paths with the file's extension.

The [@hello](hello.mdx#paginate) document is great!

See the [Tutorial](../getting-started/tutorial.mdx) for more info.

For collocated assets (files placed adjacent or near-adjacent to the docs), use relative paths as well.

![img alt](./myImage.png)

[download this file](./file.pdf)

For global assets, link to them using absolute paths.

![img alt](/myImage.png)

[download this file](/file.pdf)

Docusaurus' official recommendations: https://docusaurus.io/docs/versioning#link-docs-by-file-paths

Linking from unversioned to versioned docs​

Some docs, such as contributing and blog articles should not be versioned, unversioned content can be found in the following 2 locations:

  1. blog
  2. docs/unversioned

When linking to versioned docs from unversioned docs, these links must use the "resolved" Docusaurus path. This means the path refers to the path in the browser, not in the project folder paths. So if the address bar reads https://mssfoobar.github.io/docs/2.0.0/overview/technologies/web, https://mssfoobar.github.io is the origin and the path to the 2.0.0 version's Web Technologies section is /docs/2.0.0/overview/technologies/web.

These links must always point to an absolute version (2.0.0 in this example) of the website.

[Web Technologies](/docs/2.0.0/overview/technologies/web)
note

Remeber to EXCLUDE the extension!

Linking to unversioned docs from elsewhere​

All the docs in docs/unversioned has a base route of "stable". So instead of http://mssfoobar.github.io/docs, their routes start at http://mssfoobar.github.io/docs/stable

[changesets](/docs/stable/contributing/development/source-control#changesets)
danger

Failing to comply with these linking rules will give me great sadness because I'll have to adjust all the broken links everytime we freeze a version of the site.

How do I publish my module's Open API .json file?​

In the /static/open-api-json folder, create a new folder with the shortname of your module (e.g. for Geospatial Information Services, it would be gis), and paste your folder in there.

Example:​

Link to GIS Open API Docs: GIS Open API Docs

Code to render the above example:

Link to GIS Open API Docs: [GIS Open API Docs](/open-api-json/gis/gis-api-docs.json)

Gists​

If necessary and separate from the FAQ section, you can provide lists of commands, code recipes etc. here for users to copy-paste. These should be very short sections.

The gists below is a set of useful Docusaurus references to help you with writing your documentation for Docusaurus and is itself a good example of what gists should be.

Docusaurus Reference​

The following is a list of useful examples for reference when editing the markdown files on Docusaurus.

note

Formatting is very important for MDX: https://github.com/facebook/docusaurus/issues/3890 You must follow the formatting somewhat strictly (especially excluding spaces at the start of the sentence).

Images​

Markdown Syntax​

Svelte Logo

Code to render above example:

![Svelte Logo](/img/sample.png)

Ideal Image​

Apart from using the markdown syntax to include images, you can include <HTML> directly, such as using the <img /> tag for .mdx files... or, you can use the IdealImagecomponent from Docusaurus' @theme/idealImage. The advantage of using ideal image is that generates low-quality placeholders, supports lazy loading, and handles responsiveness for you. If you use <img /> directly, you lose all that. Here is how you can render an image with <IdealImage>.

Render Ideal Image Sample Code
import IdealImage from "@theme/IdealImage";
import sampleImage from "@site/static/img/sample.png";

<IdealImage img={sampleImage} />;

Image Sizing & Centering​

Ideal image tends to not give you the image size you want - you can wrap it with <HTML> to add whatever style you want - in this example, we limit it to 325px and add extra margins to the bottom.

You can also wrap it with a <div> with the class "centerize", which just width: 100% and flex center.

Center 
<div class="centerize">
	<div style={{ marginBottom: "2rem", marginTop: "2rem", maxWidth: "325px" }}>
		<IdealImage img={sampleImage} />
	</div>
</div>

Tabs​

shutdown -t 0 -s

Code to render above example:

<!-- You must import the React components -->

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
<TabItem value="Windows" label="Windows" default>

```bash
shutdown -t 0 -s
```

</TabItem>
<TabItem value="macOS" label="macOS">

```bash
sudo shutdown -h now
```

</TabItem>
<TabItem value="Linux" label="Linux">

```bash
sudo shutdown -h now
```

</TabItem>
</Tabs>

Codeblocks​

/src/components/HelloCodeTitle.js
function HelloCodeTitle(props) {
	return <h1>Hello, {props.name}</h1>;
}

Code to render above example:

```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) {
	return <h1>Hello, {props.name}</h1>;
}
```

Equations​

$$ I = \int_0^{2\pi} \sin(x),dx $$

Code to render above example:

$$
I = \int_0^\{2\pi\} \sin(x)\,dx
$$

Admonitions​

note

Some content with Markdown syntax. Check this api.

tip

Some content with Markdown syntax. Check this api.

info

Some content with Markdown syntax. Check this api.

caution

Some content with Markdown syntax. Check this api.

danger

Some content with Markdown syntax. Check this api.

Code to render above examples:

:::note

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::tip

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::info

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::caution

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::danger

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

Line Highlighting​

function HighlightSomeText(highlight) {
	if (highlight) {
		return "This text is highlighted!";
	}

	return "Nothing highlighted";
}

function HighlightMoreText(highlight) {
	if (highlight) {
		return "This range is highlighted!";
	}

	return "Nothing highlighted";
}

Code to render above example:

```js
function HighlightSomeText(highlight) {
	if (highlight) {
		// highlight-next-line
		return "This text is highlighted!";
	}

	return "Nothing highlighted";
}

function HighlightMoreText(highlight) {
	// highlight-start
	if (highlight) {
		return "This range is highlighted!";
	}
	// highlight-end

	return "Nothing highlighted";
}
```

Line Numbering​

import React from "react";

function MyComponent(props) {
	if (props.isBar) {
		return <div>Bar</div>;
	}

	return <div>Foo</div>;
}

export default MyComponent;

Code to render above example:

```jsx {1,4-6,11} showLineNumbers
import React from "react";

function MyComponent(props) {
	if (props.isBar) {
		return <div>Bar</div>;
	}

	return <div>Foo</div>;
}

export default MyComponent;
```