There are four essential components of aASoulDocs documentation project:

1. Configuration file
2. Template files
3. Locale files
4. Actual documents

Configuration file

The configuration file is required for every documentation project. By default, it is expected be available atcustom/app.ini.

Every server comes with abuiltin configuration file as default options. Therefore, you only need to overwrite few options in your own configuration file.

The--config (or-c) CLI flag can be used to specify a configuration file that is not located in the default location.

Template files

Template files areGo HTML templates used to render different pages served by the server.

Every server comes with a set ofbuiltin template files that works out-of-the-box. However, the content of builtin template files are probably not what you would want for your documentation in most cases, at least forhome.html andcommon/navbar.html.

Luckily, you can overwrite these template files by placing your template files with same file name under thecustom/templates directory.

For example, you can replace the "GitHub" in navbar to be a happy face by overwriting thecommon/navbar.html:

<ulclass="flex items-center space-x-5">  <li>    <aclass="hover:text-sky-500 dark:hover:text-sky-400"href="{{.Page.DocsBasePath}}">{{call.Tr"navbar::docs"}}</a>  </li>  <li>    <aclass="hover:text-sky-500 dark:hover:text-sky-400"href="https://github.com/asoul-sig/asouldocs"><!-- Heroicon: outline/emoji-happy -->      <svgxmlns="http://www.w3.org/2000/svg"class="h-6 w-6"fill="none"viewBox="0 0 24 24"stroke="currentColor"stroke-width="2">        <pathstroke-linecap="round"stroke-linejoin="round"d="M14.828 14.828a4 4 0 01-5.656 0M9 10h.01M15 10h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />      </svg>    </a>  </li></ul>

You can read more about how tocustomize templates.

Document hierarchy

Whether you want to serve your documentation in multiple languages or just one language, the hierarchy is the same. In the root directory of your documentation, you need atoc.ini file and subdirectories usingIETF BCP 47 language tags, e.g. "en-US", "zh-CN".

Here is an example hierarchy:

├── en-US│   ├── howto│   │   ├── README.md│   │   └── set_up_documentation.md│   └── introduction│       ├── README.md│       ├── installation.md│       └── quick_start.md├── zh-CN│   ├── howto│   │   ├── README.md│   │   └── set_up_documentation.md│   └── introduction│       ├── README.md│       ├── installation.md│       └── quick_start.md└── toc.ini

Thetoc.ini is used to define how exactly these documents should look like on the site (e.g. how they are ordered). The following example is a correspondingtoc.ini to the above hierarchy:

-: introduction-: howto[introduction]-: README-: installation-: quick_start[howto]-: README-: set_up_documentation

In the default section, document directories are defined in the exact order, and these names are corresponding to the directories' title:

-: introduction-: howto

Then there are sections for each directory:

[introduction]...[howto]...

Within each section, files are defined in the exact order, and these names are corresponding to the files' name in the document directory (but without the.md extension):

[introduction]-: README-: installation-: quick_start

Other notes:

1. Only single-level directories are supported.
2. Every document directory must have aREADME.md file, to at least define its name through thefrontmatter.

Localization configuration

By default, the server assumes to have documentation both in English (en-US) and Simplified Chinese (zh-CN), as in thedefault configuration:

[i18n]; The list of languages that is supportedLANGUAGES=en-US,zh-CN; The list of user-friendly names of languagesNAMES=English,简体中文

The first language in theLANGUAGES is considered as the default language, and the server shows its content if the preferred language (from browser'sAccept-Language request header) does not exists, or the particular document is not available in the preferred language (but available in the default language).

If you are just writing documentation in English, you would need to overwrite the configuration as follows:

[i18n]; The list of languages that is supportedLANGUAGES=en-US; The list of user-friendly names of languagesNAMES=English

Target

The target of documents can be either a local directory or a remote Git address.

To use a local directory:

[docs]TYPE=localTARGET=./docs

To use a remote Git address:

[docs]TYPE=remoteTARGET=https://github.com/asoul-sig/asouldocs.git

If documents are residing in a subdirectory of the target, useTARGET_DIR as follows:

[docs]TYPE=remoteTARGET=https://github.com/asoul-sig/asouldocs.gitTARGET_DIR=docs

Link to edit page

You probably want to welcome small contributions from the community if your documentation repository is open sourced. You can navigate users directly to edit the page on the code host:

[docs]; The format to construct a edit page link, leave it empty to disableEDIT_PAGE_LINK_FORMAT=https://github.com/asoul-sig/asouldocs/blob/main/docs/{blob}