--- 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](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 ```shell teedoc -f ./SUMMARY.md summary2json ``` ### From gitbook SUMMARY.md to yaml ```shell 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: ```json { "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 page `Button (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 ```json "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](./i18n.md) * `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](https://github.com) 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](./i18n.md#plug-in internationalization) 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: ```json { "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 as `site_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`: ```json { "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: ```json { "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 `` tags of all pages in the `config.json` directory. For example, if `teedoc_page` is set here, all pages in this directory will become ` ... `. 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 `` 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 ` ... `. 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](https://www.science.co.il/language/Locale-codes.php), 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 ![](../../assets/images/navbar.png) * `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 ![](../../assets/images/navbar2.png) * `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`) ![](../../assets/images/navbar2.png) * `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: ![](../../assets/images/sidebar.png) And you can add option `"collapsed": false` to show sub directory by default such as: ```yaml items: - label: Introduction to teedoc file: README.md - label: Install teedoc file: install/README.md - label: Start writing document file: usage/start.md - label: Plugin file: plugins/README.md collapsed: false items: - label: Theme Plugin file: plugins/themes.md - label: Other plugins file: plugins/others.md - label: markdown syntax file: syntax/syntax_markdown.md - label: Website using teedoc file: usage/sites.md - label: More samples items: - label: Second-level subdirectory example items: - label: Sample three-level sub-directory items: - label: Article 1 file: more/example_docs/doc1.md - label: Article 2 file: more/example_docs/doc2.md - label: This is a link url: https://github.com/teedoc/teedoc target: _blank ``` or `json` format ```json { "items":[ { "label": "Introduction to teedoc", "file": "README.md" }, { "label": "Install teedoc", "file": "install/README.md" }, { "label": "Start writing document", "file": "usage/start.md" }, { "label": "Plugin", "file": "plugins/README.md", "collapsed": false, "items":[ { "label": "Theme Plugin", "file": "plugins/themes.md" }, { "label": "Other plugins", "file": "plugins/others.md" } ] }, { "label": "markdown syntax", "file": "syntax/syntax_markdown.md" }, { "label": "Website using teedoc", "file": "usage/sites.md" }, { "label": "More samples", "items":[ { "label": "Second-level subdirectory example", "items":[ { "label": "Sample three-level sub-directory", "items":[ { "label": "Article 1", "file": "more/example_docs/doc1.md" } ] }, { "label": "Article 2", "file": "more/example_docs/doc2.md" } ] }, { "label": "This is a link", "url": "https://github.com/teedoc/teedoc", "target": "_blank" } ] } ] } ```