From a55fd1b797967fa740bdcda7a6a695592e0076f5 Mon Sep 17 00:00:00 2001 From: Leon Ding Date: Fri, 5 Jul 2024 01:28:00 +0800 Subject: [PATCH] docs: add all docs. --- README.md | 10 +++++--- book/quickstart-zh.md | 10 ++++---- book/quickstart.md | 5 ++-- book/settings-zh.md | 47 ++++++++++++++++++++++++++++++++++++++ book/settings.md | 53 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 116 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 2bf305f..29baa96 100644 --- a/README.md +++ b/README.md @@ -22,8 +22,12 @@ Typikon name derived from [Typikon](https://en.wikipedia.org/wiki/Typikon) Book, ## Preview
- Alt text - Alt text + Alt text + Alt text
---- \ No newline at end of file +--- + +## Document + +To learn how to use the `Typikon` program, you can refer to the documentation that I have written. This documentation is generally rendered and built using Typikon. The online documentation can be accessed at the following address: [https://typikonbook.github.io](https://typikonbook.github.io) 🌟. \ No newline at end of file diff --git a/book/quickstart-zh.md b/book/quickstart-zh.md index abb6e27..9036da8 100644 --- a/book/quickstart-zh.md +++ b/book/quickstart-zh.md @@ -7,13 +7,14 @@ 当下载好 zip 二进制软件包后，请使用 `unzip` 或者其他解压软件来解压 `typikon-darwin-x64-beta-v0.1.1.zip` 软件包，命令如下： ```shell -unzip typikon-darwin-x64-beta-v0.1.1.zip -d /Users/dings/devsoft +unzip typikon-darwin-x64-beta-v0.1.1.zip -d /usr/local/bin +chmod +x /usr/local/bin/typikon ``` 通过手动解压二进制到指定目录中，如果你想要全局使用 typikon 程序，那么必须将 typikon 所在的路径添加到计算机操作系统的环境变量中，例如： ```shell -export TYPIKON="/Users/dings/devsoft" +export TYPIKON="/usr/local/bin" export PATH=$TYPIKON:$PATH ``` @@ -85,7 +86,7 @@ root: ``` -而 `markdown` 文件默认存储在 `example/book` 目录中，你目前所阅读这个页面就是通过此种方式生成渲染的。 +源 `markdown` 文件默认存储在 `example/book` 目录中，你目前所阅读这个页面就是通过此种方式生成渲染的。 --- @@ -130,7 +131,8 @@ GitHub: http://typikonbook.github.io License: Apache2.0 [INFO] 2024/07/04 00:43:24 💬 Rendering of static resource files complete 🎉 ``` -使用本地服务器 `live-server` 来测试生成静态网站： +目前 typikon 程序没有内置静态文件服务器，会在未来的新版本添加支持； +可以使用本地服务器 `live-server` 来测试生成静态网站： ```shell $: live-server docs diff --git a/book/quickstart.md b/book/quickstart.md index a00f4af..284699f 100644 --- a/book/quickstart.md +++ b/book/quickstart.md @@ -7,13 +7,14 @@ To use the Typikon program, you must first install Typikon on your computer. Dur After downloading the zip binary package, unzip it using `unzip` or another decompression software. For example: ```shell -unzip typikon-darwin-x64-beta-v0.1.1.zip -d /Users/dings/devsoft +unzip typikon-darwin-x64-beta-v0.1.1.zip -d /usr/local/bin +chmod +x /usr/local/bin/typikon ``` Then manually extract the binaries to the specified directory. If you want to use the Typikon program globally, you must add the path where Typikon is located to the environment variables of your computer's operating system. For example: ```shell -export TYPIKON="/Users/dings/devsoft" +export TYPIKON="/usr/local/bin" export PATH=$TYPIKON:$PATH ``` diff --git a/book/settings-zh.md b/book/settings-zh.md index e69de29..8f18b3c 100644 --- a/book/settings-zh.md +++ b/book/settings-zh.md @@ -0,0 +1,47 @@ +## Settings + +在 `settings.yml` 文件中存储是 typikon 程序默认配置文件，可以设置 typikon 渲染出来的静态网站元数据信息，例如方便 SEO 优化的 `description` 和 `keywords` 字段，`title` 用来设置书名，其他字段用于设置作者信息。 + +```yaml +settings: + about: + title: Typikon Book + author: Leon Ding + description: Typikon name derived from Typikon Book, the a static website rendering tool similar to mdbook and hugo, but it focuses only on rendering markdown into an online book, and is easier to use than the other tools. + language: en + keywords: typikon,book,website,generator,static,html,css,js,theme,rust +``` + +在 `directory` 节点下可以设置默认，数据文件存储位置的目录和文件夹，必须是当前目录下的，可以配置目录映射关系： + +```yaml + directory: + theme: theme + source: book + output: docs +``` + + +> 所有字段必须都是 `settings` 字段子节点。 + +--- + +## Theme + +默认 typikon 程序上支持主题文件自定义的，主题文件存储在 `theme` 目录中，你只需要修改默认的 `index.html` 内容就可以到达修改其主题的目的，`assets` 目录中存储是主题依赖资源文件。默认情况不建议去修改主题文件，如果你有前端基础可以对该目录中的文件进行修改。 + +在 `settings.yml` 文件有关于主题的 `theme` 字段，通过修改字段来支持其他主题样式，可以自定义 css 文件和 js 文件，只需要将其放入 `assets` 文件夹目录中，添加对应映射关系即可： + +```yaml + theme: typikon-theme + + custom_css: + - /assets/css/bootstrap.min.css + - /assets/sidebars.css + + custom_js: + - /assets/js/bootstrap.min.js + - /assets/js/bootstrap.bundle.js +``` + +如果你的网站需要统计用户访问数据，例如 Google Analytics 对 js 文件，可以通过此种方式进行自定义配置引入。 \ No newline at end of file diff --git a/book/settings.md b/book/settings.md index e69de29..add45e2 100644 --- a/book/settings.md +++ b/book/settings.md @@ -0,0 +1,53 @@ +## Settings + +The `settings.yml` file is the default configuration file for the Typikon program, where you can set the metadata information of the static website rendered by Typikon. This includes fields for SEO optimization like `description` and `keywords`. The `title` field is used to set the book name, and other fields are used to set author information. + +```yaml +settings: + about: + title: Typikon Book + author: Leon Ding + description: Typikon name derived from Typikon Book, the a static website rendering tool similar to mdbook and hugo, but it focuses only on rendering markdown into an online book, and is easier to use than the other tools. + language: en + keywords: typikon,book,website,generator,static,html,css,js,theme,rust +``` + +In the `directory` node, you can set the default directory and folder for storing data files, which must be under the current directory. You can configure directory mappings as follows: + +```yaml + directory: + theme: theme + source: book + output: docs +``` + +> All fields must be sub-nodes of the settings field. + + +--- + +## Theme + +By default, the Typikon program supports custom theme files. Theme files are stored in the `theme` directory. You only need to modify the default `index.html` content to achieve the purpose of modifying its theme. The `assets` directory stores the theme's dependent resource files. It is not recommended to modify theme files by default, but if you have front-end skills, you can modify the files in this directory. + +In the `settings.yml` file, there is a `theme` field related to the theme. By modifying the field, you can support other theme styles. You can customize CSS and JS files by placing them in the `assets` folder and adding the corresponding mappings as follows: + + +```yaml + theme: typikon-theme + + custom_css: + - /assets/css/bootstrap.min.css + - /assets/sidebars.css + + custom_js: + - /assets/js/bootstrap.min.js + - /assets/js/bootstrap.bundle.js +``` + +If your website needs to track user visit data, such as Google Analytics for JS files, you can customize the configuration and include it in this way. + + + + +