label | order | icon | tags | |
---|---|---|---|---|
Project |
200 |
package |
|
Для настройки и построения вашего проекта docsinum будет читать файл docsinum.yml, в котором содержатся дополнительные инструкции..
Файл docsinum.yml обычно размещается в корне вашего проекта, хотя его можно поместить в другое место. Пожалуйста, убедитесь, что пути input
и output
указаны правильно, если файл был перемещен.
!!!
После внесения изменений в файл docsinum.yml, если вы запускаете docsinum start
, Docsinum автоматически перестроит проект, и ваш веб-браузер обновится с изменениями.
Если вы запустили локальный веб-сервер с помощью docsinum serve
, вам нужно вызвать docsinum build
, чтобы сгенерировать новую ✨ блестящую ✨ сборку проекта, затем вручную обновить веб-браузер, чтобы увидеть изменения. При использовании команды docsinum serve --live
все веб-браузеры автоматически обновляются.
!!!
Файл docsinum.yml является необязательным (не требуется), но рекомендуется, так как вы, скорее всего, захотите настроить некоторые параметры, поэтому добавление docsinum.yml является хорошим первым шагом.
Если вы запускаете команду docsinum start
и у вас нет файла docsinum.yml
в корне вашего проекта, Docsinum автоматически создаст простой файл docsinum.yml
для вашего проекта. Затем вы можете отредактировать файл по своему усмотрению.
Вы также можете явно указать Docsinum создать файл docsinum.yml, запустив команду docsinum init.
Ниже приведен пример настройки проекта и все параметры могут быть настроены по вашим требованиям.
input: .
output: .docsinum
url: example.com # Вставьте здесь адрес вашего веб-сайта
branding:
title: Project Name
label: Docs
links:
- text: Getting Started
link: https://docsinum.com/guides/getting-started/
footer:
copyright: "© Авторские права {{ year }}. Все права защищены."
Настройка брендинга для вашего веб-сайта, сгенерированного с помощью Docsinum..
=== title : string
Основной заголовок, добавленный в верхний левый угол сгенерированного веб-сайта.
title
можно использовать в сочетании с logo
и logoDark
. Если заданы title
и logo
, оба будут добавлены на веб-сайт. Если задан только title
, будет использоваться только текст заголовка. Если заданы только logo
и/или logoDark
, будут использоваться только логотипы.
branding:
title: Example.com
Вышеуказанный title
создаст следующий заголовок в верхнем левом углу сгенерированного веб-сайта.
=== label : string
Настраиваемый текст метки логотипа. По умолчанию - Docs
.
branding:
label: Docs
label
отображается как метка в верхнем левом углу сгенерированного веб-сайта, справа от title
или logo
.
=== logo : string
Один из следующих вариантов:
- Путь к файлу логотипа относительно
input
, или - Встроенный
<svg>
логотип
По умолчанию null
.
branding:
logo: static/logo.png
===
=== logoDark : string
Один из следующих вариантов:
- Путь к файлу логотипа (в темной теме) относительно
input
, или - Встроенный
<svg>
логотип
По умолчанию null
.
branding:
logo: static/logo.png
logoDark: static/logo-dark.png
===
=== logoAlign : string
Установка выравнивания изображения логотипа относительно title
. Поддерживаемые значения: left
и right
.
По умолчанию left
.
branding:
logo: static/logo.png
logoAlign: right
===
Настройка пользовательских цветов.
!!!warning
Значения шестнадцатеричных цветов должны быть заключены в двойные кавычки "
для избежания преобразования символа #
в комментарий.
!!!
=== label.text : string
Установка пользовательского цвета текста метки. По умолчанию "#1f7aff"
.
branding:
colors:
label:
text: "#ffffff"
===
=== label.background : string
Установка пользовательского цвета фона метки. По умолчанию "#e1edff"
.
branding:
colors:
label:
background: "#ff0000"
===
Настройки навигационной цепочки доступны только в Retype !badge PRO PRO.
Навигационная цепочка обеспечивает иерархическое представление местоположения пользователя на веб-сайте. Это упрощает навигацию по структуре контента веб-сайта, позволяя легче возвращаться назад и понимать макет сайта.
Чтобы включить или отключить навигационную цепочку в проектах Retype Pro. По умолчанию true
.
=== [!badge PRO] enabled : boolean
В проектах Docsinum Pro навигационная цепочка по умолчанию включена.
В проектах Retype (не-Pro) навигационная цепочка не будет добавляться на страницы.
Чтобы отключить навигационную цепочку на всем проекте, задайте параметру enabled
значение false
, как показано в следующем примере:
breadcrumb:
enabled: false # Отключить на всем проекте
===
Настройка home
позволяет настроить начальный узел в навигационной цепочке. Параметр может принимать значение string
или boolean
.
По умолчанию метка, использованная для первого элемента навигационной цепочки, будет меткой главной страницы проекта. Эту метку можно настроить или удалить.
=== [!badge PRO] home : string
or boolean
Установка собственной метки:
breadcrumb:
home: Home # настраиваемая метка
Использование значка icon Octicon вместо текста для узла Home:
breadcrumb:
home: ":icon-home:" # icon
Использование emoji:
breadcrumb:
home: ":rocket:" # emoji
Весь первый элемент навигационной цепочки, узел "Home", можно удалить, установив home: false
:
breadcrumb:
home: false # Не включать узел Home
===
Настройка separator
позволяет настроить разделитель между метками каждой страницы в навигационной цепочке.
=== [!badge PRO] separator : string
Использование символа вертикальной черты |
в качестве разделителя:
breadcrumb:
separator: "|"
Использование значка icon в качестве разделителя:
breadcrumb:
separator: ":icon-dot:"
===
Настройки кэша.
Конфигурация сброса кэша для ресурсов веб-сайта, таких как файлы JavaScript (.js) и CSS (.css).
Помогает убедиться, что загружаемая страница ссылается на самые последние ресурсы JavaScript и CSS.
=== strategy : string
Определяет подход, который Docsinum будет использовать для сброса кэша.
Стратегия | Описание |
---|---|
none |
Отключена сборка кэша. |
path |
Сборка кэша выполняется путем объединения имени файла с токеном версии. |
query |
Сборка кэша осуществляется путем добавления параметра запроса со значением токена версии. |
По умолчанию используется query
.
cache:
strategy: query
TODO: всё, что ниже - не отображается/не работает
Ниже приведены примеры URL-адресов, сгенерированных для соответствующих опций cache.busting.strategy
:
~~~html `strategy: none`
<script type="text/javascript" src="/resources/js/retype.js" />
~~~
~~~html `strategy: path`
<script type="text/javascript" src="/resources/js/retype.v1.10.js" />
~~~
~~~html `strategy: query`
<script type="text/javascript" src="/resources/js/retype.js?v=1.10" />
~~~
=== token : string
Необязательный уникальный токен, используемый для сброса кэша ресурсов веб-сайта.
Если указано, предоставленное значение используется как есть для всех кэшируемых ресурсов.
Если не указан, используется токен по умолчанию со следующей структурой:
{docsinum version}.{total milliseconds elapsed since 2000-01-01}
cache:
token: v5
===
=== cname : boolean
or string
!!!
В общем случае, вам не следует настраивать cname
. Пожалуйста, установите url
.
!!!
По умолчанию, если установлен url
, Retype автоматически создаст файл CNAME. Это можно отключить, установив cname: false
.
cname: false
Если вы все же хотите, чтобы был создан файл CNAME, но по какой-то причине нужно задать значение, отличное от того, которое создает url
, вы можете явно указать Retype создать файл CNAME с другим значением.
Хотя это будет очень необычный сценарий, Retype позволяет настроить эти значения отдельно, на случай, если это вам понадобится. Мы НАСТОЯТЕЛЬНО РЕКОМЕНДУЕМ вам остановиться на установке url
.
cname: docs.example.com
===
The edit
config allows for enabling and customization of the Edit this page
links on content pages.
!!!
Check out the bottom of this page for a working sample of Edit this page
.
!!!
The repository URL where the source files for this project are located.
=== repo : string
Setting a repo
value will enable the Edit this page
links on all content pages.
edit:
repo: "https://github.com/<your-organization>/<your-repo>/"
It is also possible to configure the links to point directly to the /edit/
view of the page:
edit:
repo: "https://github.com/<your-organization>/<your-repo>/edit/"
===
An optional base path to a directory within the repository.
=== base : string
The base
can be configured with an optional path to a directory within the repo
.
The following sample demonstrates how edit.base
would be configured if the .md source files for this project are stored within the /src/docs sub-directory within the repo.
edit:
repo: "https://github.com/your-organization/your-repo"
base: /src/docs
The final Edit this page URL constructed by docsinum for the sample above would be https://github.com/your-organization/your-repo/blob/main/src/docs/your-page.md
.
===
=== branch : string
Point to a custom branch within the repo. Default is main
.
edit:
repo: "https://github.com/your-organization/your-repo"
branch: master
===
=== label : string
A custom label for the link. Default is "Edit this page"
.
edit:
repo: "https://github.com/your-organization/your-repo"
label: Edit on GitHub
===
Custom configuration to control the page live editor functionality that is only available when docsinum start
is running.
To enable or disable the live editor. Default is true
.
=== enabled : boolean
Set to false
to disable and hide the live editor.
editor:
enabled: false # Default is true
===
=== exclude : list
docsinum can exclude files or folders from being built or copied to the output
by configuring an exclude
list within your projects docsinum.yml file.
Exclude patterns are similar to allowable patterns within a .gitignore
file. The wildcards ?
, *
, **
, and !
are supported.
The following sample demonstrates how to exclude an entire draft/
folder, any folder that ends with *_temp/
, and one specific /src/temp.md
file.
exclude:
- "draft/"
- "*_temp/"
- "/src/temp.md"
You could exclude everything in your project with by adding exclude: [ * ]
.
!!!
By default, any file or folder name prefixed with a .
or a _
will be excluded.
As well, any node_modules
folder will be excluded.
!!!
To explicitly include any files or folders that might have been excluded, please see the include
config.
=== favicon : string
A custom path to a .ico
or .png
file to be used as the favicon
. Default is null
.
The path is relative to the input
.
favicon: static/favicon.png
By default, docsinum will look for a favicon.ico
or favicon.png
within the root of the input
. The favicon
config would typically only be used if you want to store the favicon
file in a subfolder of the output
root.
=== copyright : string
Site-wide copyright statement that will be added to the footer of each page. Supports Markdown syntax and {{ year }}
variable.
footer:
copyright: "© Copyright {{ year }}. [Example, Inc.](https://example.com/) All rights reserved."
===
=== links : object
The footer.links
have the same configuration options as links
.
footer:
links:
- text: License
link: license.md
===
Configuration options to instruct docsinum on how and when to deal with the default directory index files, such as index.html
.
=== directoryIndex.altNames : list
A list of file names to treat as default HTML files.
By default, docsinum will treat all of the following files as default pages if they are within a folder.
generator:
directoryIndex:
altNames:
- index.html
- index.htm
- default.html
- default.htm
If you have a default.htm file within a folder and do not want it to be treated as a default page, then set altNames
to the following:
generator:
directoryIndex:
altNames:
- index.html
===
=== directoryIndex.append : boolean
Specifies if the default document file name should be appended to resolved URLs. By default, docsinum does not append the default file name.
If false
, the generated link will be /guide/
. If true
, the generated link will be /guides/index.html
.
generator:
directoryIndex:
append: true # default is false
Using append: true
in combination with the search.preload
config allows for offline file system browsing of your generated website without having to install docsinum and start a web server using docsinum start
. The following sample demonstrates how to configure:
search:
preload: true
generator:
directoryIndex:
append: true
===
=== directoryIndex.name : string
The default HTML document file name generated by docsinum.
generator:
directoryIndex:
name: default.htm # Default is index.html
===
=== paths : string
Configures url kind preference for resolved urls. Supported values: source
, relative
, and root
.
Option | Description |
---|---|
relative |
Link paths are constructed using relative paths. Example: ../../guide/introduction/ . This is the default. |
root |
Link paths are constructed using paths resolving to the website root. Example: /guide/introduction/ |
source |
Link paths are constructed using paths resolving to the source file root. |
generator:
paths: relative
===
=== recase : string
Instructs docsinum on how to recase the project file and folder names created by the author. Default is all
.
By default, docsinum will recase all the generated file and folder names to all lowercase.
Option | Description |
---|---|
all |
Covert all file and folder names in the generated output to all lowercase. This is the default. |
none |
Do not change the case of any file or folder names. |
To have docsinum NOT change the casing of any of your file or folder names, set recase
to none
.
generator:
recase: none
===
=== trailingSlash : boolean
By setting trailingSlash: false
in the project config, authors can instruct docsinum to remove (or not add) the trailing /
character when constructing links from paths to Markdown files.
For example, if you have a simple link in your project to [Example](/guide/example.md)
, docsinum will create the link as /guide/example/
. By setting trailingSlash: false
in your project, docsinum would then create the link as /guide/example
.
It is best practice to include the trailing slash and by default, docsinum will automatically add the trailing slash to links that are missing.
generator:
trailingSlash: false # default is true
===
=== include : list
docsinum can explicitly include files or folders that might have been excluded by default or excluded within the exclude
config.
!!!
If you create a link to local static file, such as .zip
file, docsinum will automatically copy that file to the generated website.
That file or file type does not need to be explicitly configured to be included. docsinum assumes that if you created a link to the file, you wanted that file published and it will be included in the output
.
!!!
Include patterns are similar to allowable patterns within a .gitignore
file. The wildcards ?
, *
, **
, and !
are supported.
The following sample demonstrates how to include all .py files, all .js files that start with the name demo
, and the entire contents of any www
folder within the project.
include:
- "*.py"
- "demo*.js"
- "**/www/**"
You could explicitly include everything in your project with include: [ "*" ]
, but be careful as all files within your input
will be publicly availble once your website is published. We would not recommend doing this, but it's your call. 😨
docsinum treats all .md and .yml files as parsable content files that will be converted into .html files and are not copied over to the output
. All other included file types would be copied straight across to the output
unchanged and become static files that can be linked to.
By default, if docsinum discovers any of the following file types, they will be automatically included and copied over to the output
unchanged. If you require any other file types, they would need to be explicitly added to the include
config.
File types that are automatically included:
*.ai
*.bmp
*.eps
*.gif
*.heif
*.htm
*.html
*.jpeg
*.jpg
*.pdf
*.png
*.svg
*.tiff
*.txt
*.webp
*.zip
By default, if docsinum discovers any of the following folders anywhere within the project, the folder and its entire contents will be copied over to the output
unchanged. If you require any other folders, please add to the include
config.
Included folders:
**/static**
**/public**
**/assets**
**/resources**
If you would rather not include certain folders, files, or file types, please add the pattern to the exclude
config.
===
=== input : string
Custom path to the input directory. Default is .
.
The path is relative to the docsinum.yml location.
input: ./src
===
More integrations
will be added over time. Do you have an integration suggestion? let us know.
Add Google Analytics to your website.
=== googleAnalytics.id : string
Google Analytics ID value.
integrations:
googleAnalytics:
id: <id>
Replace the <id>
with your Google Analytics measurement id. For example:
integrations:
googleAnalytics:
id: A-BCDEFGHIJ1
===
Add the Google Tag Manager to your website.
=== googleTagManager.id : string
Google Tag manager ID value.
integrations:
googleTagManager:
id: <id>
Specific setting to control docsinum integration with the Gravatar profile picture service and used by the page.authors configuration.
=== gravatar.default : string
The default profile image to return from Gravatar queries whenever no image is assigned to the queried email address. Default value is mp
.
Either a full URL to the image can be configured or one of the options listed below:
Value | Sample |
---|---|
404 |
Broken image |
mp (default) |
|
identicon |
|
monsterid |
|
wavatar |
|
retro |
|
robohash |
|
blank |
Blank image |
Please see the Default Image documentation on the Gravatar website.
===
=== gravatar.enabled : boolean
Whether docsinum should use Gravatar to pull profile images. Default is true
.
Setting to false
will show the default image or specified resource.
!!! Disabling Gravatar will also reset the default avatar to the docsinum default. !!!
===
Plausible.io is a simple and privacy-friendly Google Analytics alternative which can be integrated easily into docsinum generated websites.
=== plausible.domain : string
When you setup your project within Plausible, you enter a Domain
value which is then used to set the integrations.plausible.domain
config within your docsinum.yml project configuration file.
integrations:
plausible:
domain: <string>
Plausible can also send statistics to multiple dashboards by configuring a comma-separated list of domains. For example:
integrations:
plausible:
domain: domain1.com,domain2.com,subdomain.yourdomain.com
Check out the Plausible documentation for more details.
===
=== plausible.host : string
The Plausible service can be self-hosted and your docsinum project can be configured to use your custom host
.
integrations:
plausible:
host: <string>
A typical host
project configuration would look like the following sample:
integrations:
plausible:
host: plausible.example.com
If no transfer protocol is supplied, docsinum will default the host
value to use https
.
All of the following sample host
values are supported:
host: example.com
host: docs.example.com
host: https://example.com
host: http://example.com
host: example.com/js/plausible.js
host: docs.example.com/js/plausible.js
===
Custom links added to the top-bar navigation of all pages.
The following sample demonstrates a basic links
scenario which would add one link to the top bar of all pages.
links:
- text: Getting Started
link: https://docsinum.com/getting_started/
=== text : string
The link text label.
links:
- text: Demos
link: https://demo.example.com/
===
=== link : string
The URL to use for the link. The link can be a .md file name, or to any internal path, or to any external URL.
If a .md file set, such as sample.md
, docsinum will automatically resolve the path and in the generated website, the sample.md
value will be replaced with the path to the actual generated HTML file.
links:
- text: About us
link: /about/
===
=== icon : string
An icon to use with the link. Default is null
.
links:
- text: Issues
link: https://github.com/docsinumapp/docsinum/issues/
icon: bug
Options include using an Octicon name, Emoji shortcode, <svg>
element, or a path to an image file.
icon: rocket
icon: ":rocket:"
icon: <svg>...</svg>
icon: ../static/rocket.png
===
=== iconAlign : string
The position for the icon relative to the link text
. Either left
or right
. Default is left
.
links:
- text: Demos
link: https://demo.example.com/
icon: link-external
iconAlign: right
===
=== target : string
Sets the target
attribute of the hyperlink and specifies which window or tab to open the link into.
links:
- text: Demos
link: https://demo.example.com/
target: blank
If no target
is configured, the link will open in the current tab.
The target
can be set to any value, although blank
is common and will open the link in a new tab. docsinum will automatically transform the value blank
into _blank
which is the actual value required by the browser to indicate that a hyperlink should be opened in a new tab.
There are several other values that may be prefixed with an _
character, including self
, parent
, and top
. The following table demonstrates some common scenarios and naming convention used by docsinum to normalize the target
values.
Config target value |
Runtime target value |
---|---|
blank |
_blank |
parent |
_parent |
top |
_top |
self |
_self |
news1 |
news1 |
nEWs2 |
news2 |
recent NEWS |
recent-news |
===
The value of the locale
config defines the primary language that will be used on the generated website. docsinum will generate the website using system messages and labels in this language.
This flexibility makes your application more versatile and accessible to users from different languages. Currently, 24 languages are supported by docsinum.
!!! Please visit the docsinum Translation project for more details on adding new languages and making changes to existing languages. !!!
=== locale : string
You can switch the locale
to any other supported language by providing the corresponding ISO language code as listed below.
Default is en
.
The following sample demonstrates switching the project to use French.
locale: fr
===
{.compact}
Code | Language | Native name |
---|---|---|
ar |
Arabic | العربية |
da |
Danish | Dansk |
de |
German | Deutsch |
en [!badge variant="info" size="xs" text="default"] |
English | English |
es |
Spanish | Español |
fi |
Finnish | Suomalainen |
fr |
French | Français |
hi |
Hindi | हिन्दी |
hu |
Hungarian | Magyar |
hy [!badge variant="info" size="xs" text="as of v3.1"] |
Armenian (Hayeren) | Հայերեն |
it |
Italian | Italiano |
ja |
Japanese | 日本語 |
kn [!badge variant="info" size="xs" text="as of v3.1"] |
Kannada | ಕನ್ನಡ |
ko |
Korean | 한국어 |
nl |
Dutch | Nederlands |
no |
Norwegian | Norsk |
pt |
Portuguese | Português |
pt-BR |
Brazilian Portuguese | Portuguese do Brasil |
ro |
Romanian | Română |
ru |
Russian | Русский |
sa [!badge variant="info" size="xs" text="as of v3.1"] |
Sankrit (Saṁskṛtam) | संस्कृतम् |
sv |
Swedish | Svenska |
ta |
Tamil | தமிழ் |
te [!badge variant="info" size="xs" text="as of v3.1"] |
Telugu | తెలుగు |
th |
Thai | ไทย |
tr |
Turkish | Türkçe |
vi |
Vietnamese | Tiếng Việt |
zh |
Chinese | 中文 |
Markdown configuration options.
=== lineBreaks : string
Switches between soft
and hard
line break modes. The option instructs docsinum in what way a regular line ending should be handled.
- in
soft
mode, regular line breaks are processed as soft breaks (no<br />
is emitted to HTML markup), unless a line contains 2+ spaces before a line break. - in
hard
mode, regular line breaks are always emitted as<br />
HTML elements.
Default is soft
.
markdown:
lineBreaks: soft # or, hard
===
Project wide meta tag configuration options.
=== title : string
Common site-wide suffix appended to the html <title>
element of all pages. Default is null
.
meta:
title: " | Example.com - Widgets for the internet"
Using the sample above, if we had an About us
page, the final <title>
would be:
<title>About us | Example.com - Widgets for the internet</title>
!!!
See also, the Page level meta.title
configuration.
!!!
This config is docsinum !badge PRO only.
The outbound
configuration gives you the flexibility to customize the behavior of outbound links in your docsinum project. It allows you to control which links are treated as outbound, where they open, what icon is used, and even exclude or include specific domains. For instance, example.com.
The outbound
functionality will be automatically enabled for docsinum Pro project. For projects that do not have a docsinum Pro license, the outbound
configuration and functionality is ignored.
If outbound
is enabled, docsinum will find all external (outbound) links within the project, add a trailing :icon-link-external: icon, and set the link to open in a new tab when clicked.
=== [!badge PRO] enabled : boolean
Controls whether the outbound links feature is enabled.
The default is true
for docsinum Pro projects.
The following sample demonstrates disabling the outbound
functionality:
outbound:
enabled: false
===
=== [!badge PRO] custom : string
Provides a way to specify custom attributes to be added to the outbound links. The default value is empty/null.
The following sample demonstrates how to add the attribute rel="noopener noreferrer"
to all outbound links:
outbound:
custom: 'rel="noopener noreferrer"'
===
=== [!badge PRO] icon : string
Defines the icon to be used for outbound links and accepts all the same options as the links.icon
config. The default value is link-external
:icon-link-external:.
outbound:
icon: link-external
If you would prefer to keep the outbound
functionality enabled, but not include the :icon-link-external: icon, please set icon: ""
. The following sample demonstrates:
outbound:
icon: ""
===
=== [!badge PRO] iconAlign : string
Determines the alignment of the icon for outbound links and accepts the same options as the links.iconAlign
config. Acceptable values are right
or left
. The default value is right
.
outbound:
iconAlign: right
===
=== [!badge PRO] target : string
Specifies the target
attribute for the outbound links. The default value of "blank"
opens the link in a new window or tab.
outbound:
target: blank
===
=== [!badge PRO] exclude : list
A list of outbound link patterns to be excluded from being captured by the docsinum outbound functionality. This is useful if you do not want certain links to open in new tabs.
This configuration accepts similar path patterns as the exclude
config.
The following sample demonstrates excluding all links pointing to example.com
.
outbound:
exclude:
- example.com
Please also see outbound.include
.
===
=== [!badge PRO] include : list
A list of outbound link patterns to be included for the docsinum outbound functionality. This is useful if you only want certain links to open in new tabs. The default value of *
includes all links.
This configuration accepts similar path patterns as the include
config.
The following sample demonstrates including only links that point to example.com
.
outbound:
include:
- example.com
If any item is added to the include
list, by default, all other paths will be excluded. Please also see outbound.exclude
.
=== output : string
Custom path to the output directory. Default is .docsinum
.
The path is relative to the docsinum.yml location.
output: ./docs
===
This config is docsinum !badge PRO only.
Controls whether to include or exclude the Powered by docsinum
branding.
=== [!badge PRO] poweredBydocsinum : boolean
With a docsinum Pro license, the Powered by docsinum
branding can be removed by setting to false
.
poweredBydocsinum: true # Set to `false` to remove.
===
Customization of the website search component.
=== hotkeys : list
Keyboard key to set the cursor focus into the search field. Default is k
.
The following sample demonstrates how to change the search hotkey to use /
instead of the default k
:
search:
hotkeys:
- "/"
===
=== maxResults : number
Max number of search results to render. Default is 20
.
search:
maxResults: 20
===
=== minChars : number
Min number of characters required in a search query. Default is 2
.
The following sample demonstrates how to configure search.minChars
with a new value:
search:
minChars: 3
===
=== mode : string
The search index creation mode. Default is full
.
Mode | Description |
---|---|
full |
A full-text search index of the project content is made. Includes all headings and all text content. |
partial |
All headings plus the first paragraph under each heading is used to create the search index. The Page description config is also included if not empty. |
basic |
All headings plus only the first paragraph of each page is used to create the search index. The Page description config is also included if not empty. |
The following sample demonstrates how to configure search.mode
with a new value:
search:
mode: partial
!!!
If your project includes a lot of content and your users find the search is running too slow, try changing to mode: partial
or even a mode: basic
if the website is really huge.
!!!
=== noResultsFoundMsg : string
Message rendered when no results were found. Default is "Sorry, no results found."
.
search:
noResultsFoundMsg: Sorry, no results found.
===
=== placeholder : string
Placeholder text rendered on the search component. Default is "Search"
.
search:
placeholder: Search
===
=== preload : boolean
Specifies if the search index should be preloaded. Default is false
.
search:
preload: true # Default is false
Using preload: true
in combination with the generator.directoryIndex.append
config allows for offline file system browsing of your generated website without having to install docsinum and start a web server using docsinum start
. The following sample demonstrates how to configure:
search:
preload: true
generator:
directoryIndex:
append: true
===
Custom configuration for the built in docsinum development web server.
=== host : string
Serve the website from this host location. Default is localhost
.
serve:
host: 127.0.0.1
By default, the docsinum development web server will serve from http://localhost:5000
, although the port could be dynamically assigned if port 5000
is already in use.
A custom port value can also be assigned.
serve:
host: 127.0.0.1:5005
A custom --host
value can also be passed as an argument to the docsinum start
and docsinum serve
commands. If included, the --host
value will override the host
set within your docsinum.yml project configuration file.
docsinum start --host 127.0.0.1 # serve from a custom host
docsinum start --host 127.0.0.1 --port 5005 # serve from a custom host and port
===
=== port : number
A custom port for the internal docsinum development web server to use when hosting locally. Default is 5000
.
serve:
port: 5005
If the default port is already being used by another service, docsinum will auto-increment the port number until it finds an open port to host from.
If a custom port
is explicitly configured in the docsinum.yml and if that port is already being used by another service, docsinum will write a message to the console and exit. In that scenario, because the port
was explicitly configured, docsinum will not attempt to auto-increment.
!!!
The port number can also be included in the host
config.
!!!
A custom --port
value can also be passed as an argument to the docsinum start
and docsinum serve
commands. If included, the --port
value will override the port
set within your docsinum.yml project configuration file.
docsinum start --port 5005 # serve from a custom port
===
Custom configuration for the docsinum serve
and docsinum start
commands.
=== mode : string
During docsinum start
and docsinum serve
, the mode
configuration instructs the web server on where to host files from.
If memory
, the entire website is built and then stored in memory during development with no files being written to disk.
If disk
, the entire website is built and written to disk, then the web server will host those files from their disk location.
Default is memory
.
Mode | Description |
---|---|
memory |
No output files are written to a disk. docsinum serves a website from the in-memory storage. |
disk |
Output files are written to the output directory, and updated with each incremental build accordingly. |
serve:
watch:
mode: disk
The command docsinum build
will always build and write all files to disk. The memory
configuration is not an option with docsinum build
. The docsinum GitHub Action uses docsinum build
. The command docsinum start
is only to be used during local development and not on a live production web server.
===
=== polling : boolean
or number
Instructs the local web server on how it should listen for file changes.
If false
, the native filesystem event listeners are used to monitor for file changes.
If true
, docsinum will poll for file changes within your projects input directory. By default, the polling interval is 1000 milliseconds (1 second).
The poll interval is configurable by setting a number
value. For instance, setting polling: 500
would configure a 500ms interval.
Default is false
.
Polling | Description |
---|---|
false |
Use native filesystem event listeners to receive file change notifications the project input directory. |
true |
Poll the input directory for changes every 1000 milliseconds (1 second). |
number |
Poll the input directory in milliseconds. |
serve:
watch:
polling: true
!!! Performance Warning Disk polling may be a costly operation, especially in projects with a large quantity of files, and/or running over remote mounted directories (ftp mapping, NFS, SMB...). If configuring the poll interval, please adjust the value down in steps, monitoring performance as the poll interval decreases.
On the flip side, increasing the polling interval may cause an annoying experience during docsinum start
as file changes will require a longer time before reflected in the browser.
!!!
===
=== validation : string
Configure how thorough docsinum is while looking for changed files.
Default value is optimal
.
Validation | Description |
---|---|
fast |
Compare file system metadata only (reported file size and last modification time). |
full |
Perform full SHA2 comparison on every tracked file. |
optimal |
Compare file system metadata and, for every file with changes, perform SHA2 comparison. |
===
The snippets
configuration allows for the project with custom configuration of code block formatting, including the project wide enabling of line numbering.
=== lineNumbers : list
A list of code block reference language strings to enable line numbering on. Default is null
.
snippets:
lineNumbers:
- js
- json
Configuring the "*"
wildcard will enable line numbering for all code block types, including code blocks with no explicit reference language.
snippets:
lineNumbers:
- *
Enabling line numbering site wide on code blocks with no explicit reference language is configured with the none "none"
specifier.
snippets:
lineNumbers:
- none
===
The start
config contains project options that apply during the docsinum start
CLI command.
=== open : boolean
Set to false
to instruct docsinum to not open the default web browser when the command docsinum start
is run. By default, docsinum will open a web browser when docsinum start
is run.
The default is true
.
The following sample demonstrates how to prevent the default web browser from opening during docsinum start
:
start:
open: false
Using the CLI command docsinum start -n
or docsinum start --no-open
will also prevent the default web browser from being opened.
===
Configurations to control the docsinum content templating engine for this project.
=== enabled : boolean
A project-wide option to enable or disable the docsinum content templating engine. Default is true
.
templating:
enabled: true # Set to false to disable
The templating engine can also be disabled on a per-page basis by setting templating: false
in the page metadata.
===
=== liquid : boolean
Specifies if Liquid syntax {% ... %}
is enabled. If liquid: true
is set, docsinum is incompatible with GitBook style of component configuration.
Default is false
.
templating:
liquid: false # Set to true to enable
===
=== url : string
The base URL of your website.
url: example.com
The url
can also be a subdomain.
url: docs.example.com
If you deploy your docsinum generated website into the subfolder of another website, add the subfolder in the url
. For example, if the website will be available at https://example.com/docs
, add that docs
folder name to the url
.
url: example.com/docs
If no protocol is supplied, such as https
or http
, docsinum will assume https
. A protocol can be explicitly defined by passing in the url
.
url: http://example.com/docs/
Another common scenario for setting a url
is when using GitHub Pages without a custom CNAME.
For instance, if your GitHub organization was CompanyX
and your repo was named docs
, the URL to your GitHub Pages hosted website would be https://companyx.github.io/docs/
.
docsinum needs to know where your website will be hosted, so the url
configuration for the above scenario would be:
url: companyx.github.io/docs
===
Option | Type | Default value | Description |
---|---|---|---|
api |
object |
API reference doc generation | |
api.input |
string |
Path to a project file or a project directory | |
api.output |
string |
./api |
Custom path to the API output directory. Relative to output |