SystemDev/DocServe: 在线文档仓库 @ 35e92fc0d35690f7ef31c6c63d618312b336f806

title: start writing document keywords: teedoc, markdown, jupyter notebook, html, document generation, alternative gitbook, website generation, static website, document writing

desc: teedoc, convert markdown or jupyter notbook into html static web pages, introduce the basic use of teedoc

Build and Preview

Execute in the document directory with site_config.json

teedoc serve

After displaying Starting server at 0.0.0.0:2333 ...., it is fine

Open the browser to visit: http://127.0.0.1:2333

Modify the file in real time. After saving the file, it will automatically rebuild the file after 3 seconds by default, and then the browser will automatically refresh

The delay time of automatic refresh can be set, you can add the -t parameter, for example, teedoc -t 0 serve is set to a 0 second delay, It can also be set in the document configuration, see the description of the configuration parameter rebuild_changes_delay below

If you only need to build and generate HTML pages, you only need to execute

teedoc build

! Note that if you are finally generating the release version of the document, you must use the build command to generate the website page, the page generated by the serve command can only be used for local preview, there will be redundant preview related code, which is not suitable Used in production deployment

In addition, you can also specify the parameter -d or --dir to specify the document directory, so that you do not need to execute commands under the document directory, such as

teedoc -d /home/teedoc/my_doc build

Build document delete

The built document will be placed in the out directory, the program will not actively delete it, if you need to clear it, please delete it manually

Document directory structure

├─.github
├─docs
│ ├─develop
│ │ ├─en
│ │ └─zh
│ └─get_started
│ ├─assets
│ ├─en
│ └─zh
├─pages
│ └─index
│ ├─en
│ └─zh
├─static
│
└─site_config.json

.github: automatic build script, how to use it in later chapters
docs: document, contains multiple documents, each document is a separate folder
pages: pages, including homepages, 404 pages, etc.
static: static file folder, such as storing pictures
site_config.json: website configuration file
config.json: In addition to site_config.json, each document directory can have config.json to configure document related pages
sidebar.json: document directory

Before looking at how to use the configuration file, you must keep in mind that the configuration file is very simple. The configuration file has only two file names, a unique document configuration file site_config and each document's own configuration file config

Configuration file

The configuration file can be a file in json or yaml format, choose the one you like. Don't be afraid if you haven't touched it before, search for a tutorial and take 10 minutes to learn it.

If your document directory has a lot of content, it is recommended to use the yaml format, which looks more concise

teedoc provides commands for converting between json and yaml formats

From json to yaml

teedoc -f ./config.json json2yaml

From yaml to json

teedoc -f ./config.json yaml2json

From gitbook SUMMARY.md to json

teedoc -f ./SUMMARY.md summary2json

From gitbook SUMMARY.md to yaml

teedoc -f ./SUMMARY.md summary2yaml

site_config.json Site configuration

Website configuration items, such as website name, page routing, plug-in configuration, etc.

The following sample configuration file looks like there are many configuration items, don’t be scared, in fact it is very simple, the main configuration items, mastered, thinking is easy

The configuration file is in json format, for example:

{
    "site_name": "teedoc",
    "site_slogon": "happy to write",
    "site_root_url": "/",
    "site_domain": "teedoc.github.io",
    "site_protocol": "https",
    "config_template_dir": "./",
    "source": "https://github.com/teedoc/teedoc.github.io/blob/main",
    "route": {
        "docs": {
            "/get_started/zh/": "docs/get_started/zh",
            "/develop/zh/": "docs/develop/zh",
        },
        "pages": {
            "/": "pages/index/zh",
        },
        "assets": {
            "/static/": "static",
            "/get_started/assets/": "docs/get_started/assets"
        },
        "/blog/": "blog"
    },
    "translate": {
        "docs": {
            "/get_started/zh/": [ {
                    "url": "/get_started/en/",
                    "src": "docs/get_started/en"
                }
            ],
            "/develop/zh/": [ {
                    "url": "/develop/en/",
                    "src": "docs/develop/en"
                }
            ]
        },
        "pages": {
            "/": [ {
                    "url": "/en/",
                    "src": "pages/index/en"
                }
            ]
        }
    },
    "executable": {
        "python": "python3",
        "pip": "pip3"
    },
    "plugins": {
        "teedoc-plugin-markdown-parser":{
            "from": "pypi",
            "config": {
            }
        },
        "teedoc-plugin-theme-default":{
            "from": "pypi",
            "config": {
                "dark": true,
                "env":{
                    "main_color": "#4caf7d"
                },
                "css": "/static/css/custom.css",
                "js": "/static/js/custom.js"
            }
        }
    }
}

site_name: site name
site_slogon: website slogan
site_root_url: website root directory path, use the default value /; if you need to put the generated content in the website folder (not the root directory folder), you can set
site_domain: website domain name, currently used place: generate sitemap.xml and robots.txt
site_protocol: website protocol, http or https, currently used place: generate sitemap.xml and robots.txt
config_template_dir: config template file, config.json or config.yaml in other document directories can be import the files in it, the default location is the directory where site_config is located
source: document source path, such as https://github.com/teedoc/teedoc.github.io/blob/main, where main is the main branch of the document, and Edit this page' will be added to the document pageButton (link), click to jump to the source code of the corresponding file. You can leave it blank to not add a link. In addition, you can add "show_source": "Edit this page" in config.json to define the text content of the button as Edit this page, if you want the document to have no such button, set it to "show_source": false; you can also add show_source: edit this page or show_source: false in the header information of the file (md or ipynb file) to set
route: Web page routing, including routing of documents, pages and resource files, such as routing of documents
```
"docs": {
"/get_started/zh/": "docs/get_started/zh",
"/get_started/en/": "docs/get_started/en",
"/develop/zh/": "docs/develop/zh",
"/develop/en/": "docs/develop/en"
},
```
The key represents the url of the document in the final generated website, and the following value is the corresponding source document path. For example, the source document docs/get_started/zh/README.md will generate the file out/get_started/zh/index.html after construction. If it is not a md file (ie unsupported file), it will be left intact Copy files automatically, and finally the out directory is the generated website

The same is true for pages, assets will not perform document conversion and directly copy to the corresponding directory

translate: Translate, specify the url and file path of the translated version corresponding to the document. Similarly, the config and sidebar configuration files are required under the path of the translated version, and locale is specified in the config file To achieve the specified document language to be translated, for example, Chinese can be zh, zh_CN, zh_TW, English is en, en_US, etc. The translated sidebar and the document path need to be consistent with the source document. If there is no translation, you can leave the translation file. When the user visits a page that has not been translated, it will jump to no_tanslate.html to indicate that there is no translation. For more details, please see Internationalization i18n
executable: executable program settings, here you can set the executable program names of python and pip, which will be used when installing the plug-in
plugins: Plug-in configuration, mainly composed of name, source, and configuration items. For the name, you can search for teedoc-plugin in github to find open source plug-ins. You are also welcome to participate in writing plug-ins (you only need to use the Python syntax); Fill in the from field with pypi, if the plug-in is downloaded locally, you can also fill in the folder path, or you can fill in the git path directly, such as git+https://github.com/*****/* *****.git The configuration items are determined by the specific plug-in. For example, teedoc-plugin-theme-default has the dark option to choose whether to enable the dark theme
rebuild_changes_delay: After detecting file changes, how many seconds to delay automatically regenerating the document, the browser will automatically refresh the page, the default is 3 seconds, the shortest can be set to 0 seconds, you can use teedoc -t 3 serve or teedoc --delay serve to override this setting
robots: Customize the content of robots.txt, such as "User-agent": "*" means that all clients are allowed to crawl, which will have an impact on SEO. For example, crawling of JPEG pictures is not allowed: "Disallow": "/.jpeg$", and access to the admin directory: "Disallow": "/admin" is not allowed, specifically and robots.txt Same format requirements
layout_root_dir: the root directory of the layout template, the default is layout, that is, when the layout template file is needed, it will automatically find it under this folder
layout_i18n_dirs: The international translation directory of layout, which can be a path such as locales, and in some special cases, multiple paths such as ["locales1", "locales2] can also be set. The content of the file can be referred to i18n production

config.json document configuration

This is the configuration for each document, placed in the root directory of each document, such as docs/get_started/zh/config.json, each document is independent of each other, you can set the same to keep the website navigation bar consistent

Here you can configure the navigation bar of each document and the content of the footer (footer), and you can also set the config item of the plug-in. The current document will override the configuration in site_config.json to achieve different Documents in different languages (internationalization/i18n) or styles, etc.

such as:

{
    "import": "config_zh",
    "id": "teedoc_page",
    "class": "language_zh",
    "locale": "en_US",
    "navbar": {
        "title": "teedoc",
        "logo": {
            "alt": "teedoc logo",
            "src": "/static/image/logo.png"
        },
        "home_url": "/",
        "items": [
            {
                "url": "/get_started/zh/",
                "label": "Installation and Use",
                "position": "left"
            },
            {
                "url": "/develop/zh/",
                "label": "Development",
                "position": "left"
            },
            {
                "url": "https://github.com/neutree/teedoc",
                "label": "github",
                "target": "_blank",
                "position": "right"
            },
            {
                "label": "Language: ",
                "position": "right",
                "items": [
                    {
                        "url": "/get_started/zh/",
                        "label": "Chinese"
                    },
                    {
                        "url": "/get_started/en/",
                        "label": "English"
                    }
                ]
            }
        ]
    },
    "footer":{
        "top":[
            {
                "label": "Link",
                "items": [
                    {
                        "label": "Use teedoc to build",
                        "url": "https://github.com/neutree/teedoc",
                        "target": "_blank"
                    },
                    {
                        "label": "Copyright © 2021 Neucrack",
                        "url": "https://neucrack.com",
                        "target": "_blank"
                    }
                ]
            },
            {
                "label": "Source",
                "items": [
                    {
                        "label": "github",
                        "url": "https://github.com/neutree/teedoc",
                        "target": "_blank"
                    },
                    {
                        "label": "Source files of this website",
                        "url": "https://github.com/teedoc/teedoc.github.io",
                        "target": "_blank"
                    }
                ]
            }
        ],
        "bottom": [
            {
                "label": "*ICP备********号-1",
                "url": "https://beian.miit.gov.cn",
                "target": "_blank"
            },
            {
                "label": "*Public Network Security No. ************",
                "url": "https://beian.miit.gov.cn/#/Integrated/index",
                "target": "_blank"
            }
        ]
    },
    "plugins": {
        "teedoc-plugin-search":{
            "config": {
                "search_hint": "Search",
                "input_hint": "Enter keywords, separate multiple keywords with spaces",
                "loading_hint": "Loading, please wait...",
                "download_err_hint": "Failed to download the file, please refresh and try again or check the network",
                "other_docs_result_hint": "Results from other documents",
                "curr_doc_result_hint": "Current document search result"
            }
        }
    },
    "show_source": "Edit this page"
}

import: You can import the configuration from the template file, the file name without suffix. For example, site_config set config_template_dir to ./, fill in "import": "config_zh" here, it means to import config_zh.json (priority) or config_zh in the same directory assite_config.yaml. Then you can add the configuration of the current document, overwrite the template file, the same keywords, and modify different content. If it is an array (list), to replace the content of the template file, you need to add id to the array item of the template file. Keyword, then modify, if the id keyword is not specified, it will be appended to the array. For example, the template file config_zh:

{
"locale": "en_US",
"navbar": {
    "title": "teedoc",
    "items": [
        {
            "url": "/get_started/zh/",
            "label": "安装使用",
            "position": "left"
        },
        {
            "id": "language",
            "label": "Language: ",
            "position": "right",
            "items": [
                {
                    "url": "/zh",
                    "label": "中文"
                },
                {
                    "url": "/en",
                    "label": "English"
                }
            ]
        }
    ]
}
}

The configuration file of a specific document:

{
"import": "config_zh",
"navbar": {
    "title": "teedoc123",
    "items": [
        {
            "id": "language",
            "label": "Language: ",
            "position": "right",
            "items": [
                {
                    "url": "/get_started/zh",
                    "label": "中文"
                },
                {
                    "url": "/get_started/en",
                    "label": "English"
                }
            ]
        }
    ]
}
}

id: The id of the document. Generally, there is no need to write it. The id will be set to the <html> tags of all pages in the config.json directory. For example, if teedoc_page is set here, all pages in this directory will become <html id="teedoc_page"> ... </html>. If the markdown file has set id, this value will be overwritten, that is, each page can only have one id.
class: The class of the document, generally you don't need to write it. Set the class to the <html> tags of all pages in the config.json directory, and use spaces for multiple class Separate. For example, if language_zh is set here, all pages in this directory will become <html class="language_zh"> ... </html>. If class is set in the markdown file, it will be appended. For example, if language_zh is set in config.json, and class: zh_readme is set in README.md, the final result is class=" language_zh zh_readme". This function is convenient to customize the style of each page or the style of different documents.
locale: locale code, can found from here, for example: zh, zh_CN, en_US, ja etc. Or get by program babel:
```
pip install babel
pybabel --list-locales
```
navbar: Navigation bar settings, each document can be individually set up the navigation bar, if you want to keep the entire website unified, you can modify each configuration to be the same. The keyword type is used in the first layer and is used to indicate the category of this label in the navigation bar. The values are:
- link: normal link, this option is the default when you don’t write the type keyword
- list: There are sub-items, which will be displayed in the form of a drop-down menu
- selection: Single option, such as language selection. When the type keyword is not written and there is the items keyword, this option is the default
- language: If translate is set in site_config, the items of type language will be automatically filled in the language list, so we don't need to write the language list manually! The effect is the same as selection (in fact, the internal code is to automatically replace the language type with selection)
footer: website footer, divided into upper and lower parts, and multiple columns can be added to the upper part, and each column can have multiple values
plugins: Configure the configuration items of the plug-in, if it has been set in the site_config.json, it will be overwritten, that is, the priority of the child config is higher
show_source: Under the premise that the keyword source is set in site_config.json, it is the source code path of the document, such as https://github.com/teedoc/teedoc.github.io/blob/main , Where main is the main branch of the document, and the Edit this page button (link) will be added to the document page, click to jump to the corresponding file source code. Set "show_source": "Edit this page" to define the text content of the button as Edit this page, if you don't set it, the default is Edit this page, if you want the document to have this button, set it to "show_source": false; you can also add show_source: edit this page or show_source: false in the header information of the file (md or ipynb file) to set

sidebar.json Document directory (sidebar) settings

There is a directory for setting documents, one for each document, independent of each other

The file path uses a relative path, just fill in the file name, README.md will be automatically converted to index.html

In addition, you can also directly url without writing the path of file, such as "url": "/get_started/zh/", at the same time you can set "target":"_blank" to open in a new window, otherwise Open in current window

For the items in the first layer of items, if there is only label without url, file and items, a classification mark will be added to the sidebar, and the effect is as follows:

And you can add option "collapsed": false to show sub directory by default