STech Docs简介
docusaurus建站
参考
- docusaurus官网
- docusaurus Github
- 项目配置说明
- Markdown文件
- MarkDown语法和特色功能
- 代码块主题 | codeblock | code prism
- 搜索功能
安装
# 1 安装node【docusaurus是react项目，如果node没安装，需要安装node】
# - mac 参考: mac-reinstall-homebrew > 用brew安装常用程序和库 > 安装 nvm | 安装 node
# - ubuntu: apt show nodejs && apt install nodejs && node -v && nvm -v
# 2 创建项目
$ npx create-docusaurus@latest my-website classic
# 3 拷贝已有的MarkDown文档到项目docs目录
$ cd my-website/docs
$ mkdir tech && cd ..
$ cp -f ~/s/github/s-technical-docs/technical/os-ubuntu/*.md docs/tech/os-ubuntu
$ cp -f ~/s/github/s-technical-docs/technical/os-zspace/*.md docs/tech/os-zspace
$ cp -f ~/s/github/s-technical-docs/technical/MySQL/*.md docs/tech/MySQL
$ cp -f ~/s/github/s-technical-docs/technical/commands/*.md docs/tech/commands
调试和发布
# 1 本地调试应用
$ cd ~/gitea/rn/my-website
$ npm start
# 2 打包发布
$ cd ~/gitea/rn/my-website
$ npm run build
# 3 线上用nginx发布
# - 通过gitea 项目代码管理工具 管理项目
# - 本地打包，并提交到gitea
# - 服务端 直接 git pull 即可完成发布
# - 通过nignx 来发布项目
$ ln -s /var/www/my-s-tech-site/nginx/prod.conf www.s.tech.conf
$ nginx -t
$ systemctl restart nginx
$ systemctl status nginx
# - 通过certbot 自动签发证书
certbot certonly --manual --preferred-challenges dns -d www.s.tech
nginx部署
server {
listen 80;
listen [::]:80;
listen 443 ssl;
listen [::]:443 ssl;
ssl_certificate "/etc/ssl/s-tech/full_chain.pem";
ssl_certificate_key "/etc/ssl/s-tech/private.key";
server_name www.s.tech;
root /var/www/my-s-tech-site/build;
# Add index.php to the list if you are using PHP
index index.html index.htm index.nginx-debian.html;
location / {
# First attempt to serve request as file, then
# as directory, then fall back to displaying a 404.
try_files $uri $uri/ =404;
}
}
菜单导航和侧边栏
-
顶部菜单导航栏配置
################# 顶部菜单栏配置 #################
# 配置位置: docusaurus.config.js / themeConfig / navbar / items
# navbar: https://docusaurus.io/docs/api/themes/configuration#navbar
# items: https://docusaurus.io/docs/api/themes/configuration#navbar-items
items: [
# 左边顶部菜单 对应的是侧边栏目录模式
{
type: 'docSidebar',
sidebarId: 'techSidebar',
position: 'left',
label: 'STech Docs',
},
# 左边顶部菜单 对应的是单个文档
{
type: 'doc',
position: 'left',
docId: 'common-command',
label: 'Commands',
},
{
type: 'docSidebar',
sidebarId: 'tutorialSidebar',
position: 'left',
label: 'Tutorial',
},
{
to: '/blog',
label: 'Blog',
position: 'left'
},
# 右边顶部菜单 对应的是外部链接
{
href: 'https://gitea.s.tech',
label: 'Gitea',
position: 'right',
},
],
################# 顶部菜单栏配置 ################# -
侧边栏配置
//////////////////// 文章列表侧边栏配置 ////////////////////
// 配置位置: sidebars.js
// 配置说明: https://docusaurus.io/docs/sidebar
// 例子: https://docusaurus.io/docs/sidebar#complex-sidebars-example
/**
@type {import('@docusaurus/plugin-content-docs').SidebarsConfig}
*/
const sidebars = {
tutorialSidebar: [{type: 'autogenerated', dirName: 'tutorial'}],
techSidebar: [
'tech-intro',
{type: 'autogenerated', dirName: 'tech'}
],
};
// techSidebar侧边栏 有两部分组成
// - 侧边栏第一个文章为 'tech-intro'
// - 侧边栏剩余文章 通过自动解析 docs/tech/ 目录下的所有MarkDown文件生成
//////////////////// 文章列表侧边栏配置 //////////////////// -
侧边栏文章排序
# 1 自动解析目录生成侧边栏文章列表，无法指定排序
# 2 要排序 需要手动设置侧边栏文章列表 比如
items: [
'guides/creating-pages',
{
type: 'category',
label: 'Docs',
link: {
type: 'doc',
id: 'guides/docs/introduction',
},
items: [
'guides/docs/create-doc',
{
type: 'category',
label: 'Sidebar',
link: {
type: 'doc',
id: 'guides/docs/sidebar/index',
},
items: [
'guides/docs/sidebar/items',
'guides/docs/sidebar/autogenerated',
'guides/docs/sidebar/multiple-sidebars',
],
},
'guides/docs/versioning',
'guides/docs/multi-instance',
],
] -
侧边栏文件夹排序和文件夹绑定的文章
# 通过在文件夹中增加_category_.json文件来配置
# 配置说明: https://docusaurus.io/docs/sidebar/autogenerated#category-item-metadata
# 下面配置 = 当前子文件夹在侧边栏排第二个 + 将子文件夹中的MarkDown文章以卡片的形式
{
"label": "Ubuntu Centos Configs",
"position": 2,
"link": {
"type": "generated-index",
"title": "Ubuntu Centos 配置"
}
}
主题和代码块
################# 项目主题配置 #################
# 配置文档: https://docusaurus.io/docs/api/themes/configuration
# 默认的主题: 作用于整个项目【项目自带 无需另外安装】
# - @docusaurus/theme-classic【https://docusaurus.io/docs/api/themes/@docusaurus/theme-classic】
# 功能增强性主题: 作用于项目某个功能模块【项目自带 无需另外安装】
# - @docusaurus/theme-live-codeblock【可编辑代码块主题 https://docusaurus.io/docs/api/themes/@docusaurus/theme-live-codeblock】
# - @docusaurus/theme-search-algolia【搜索功能主题 https://docusaurus.io/docs/api/themes/@docusaurus/theme-search-algolia】
################# 项目主题配置 #################
################# 代码块主题配置 #################
# 配置位置: docusaurus.config.js / themeConfig / prism
# 代码块支持的语言: https://docusaurus.io/zh-CN/docs/markdown-features/code-blocks#supported-languages
# 主题颜色: https://github.com/FormidableLabs/prism-react-renderer/tree/master/packages/prism-react-renderer/src/themes
# - dracula | duotoneDark | duotoneLight
# - gruvboxMaterialDark | gruvboxMaterialLight
# - jettwaveDark | jettwaveLight
# - nightOwl | nightOwlLight
# - oneDark | oneLight
# - vsDark | vsLight
# - github | oceanicNext | okaidia | palenight | shadesOfPurple | synthwave84 | ultramin
prism: {
theme: prismThemes.jettwaveLight,
darkTheme: prismThemes.dracula,
additionalLanguages: ['powershell','bash','nginx'],
},
################# 代码块主题配置 #################
搜索功能
-
algolia搜索【algolia】
////////////////////////////// 网站搜索 【algolia】 ///////////////////////////////
// 文档地址: https://docusaurus.io/docs/search#using-algolia-docsearch
// DocSearchGithub: https://github.com/algolia/docsearch
// 从DocSearch申请Algolia API-Key用于网站搜索: https://docsearch.algolia.com/apply/
// algolia后台地址: https://dashboard.algolia.com/apps/MR2E63AMAD/dashboard
// 步骤1 从DocSearch申请“Algolia API-Key”用于网站搜索
// 步骤2 配置algolia 参考【https://docusaurus.io/docs/search#connecting-algolia】
algolia: {
appId: 'MR2****MAD', // The application ID provided by Algolia
apiKey: '1fcb78*********************cbfe4', // Public API key: it is safe to commit it
indexName: 's***m',
contextualSearch: true, // Optional: see doc section below
searchParameters: {}, // Optional: Algolia search parameters
searchPagePath: 'search', // Optional: path for search page that enabled by default (`false` to disable it)
insights: false, // Optional: whether the insights feature is enabled or not on Docsearch (`false` by default)
},
////////////////////////////// 网站搜索 【algolia】 /////////////////////////////// -
自建搜索服务【typesense-docsearch】
################# 网站搜索【typesense-docsearch】 #################
# 配置文档: https://docusaurus.io/docs/search#using-typesense-docsearch
# 服务搭建方式:
# - 购买Typesense cloud 云服务【https://cloud.typesense.org/】
# - 自己搭建 Typesense搜索服务【https://typesense.org/docs/guide/install-typesense.html#option-2-local-machine-self-hosting】
# 功能组成:
# - typesense-docsearch-scraper【typesense文档爬虫 https://github.com/typesense/typesense-docsearch-scraper】
# - docusaurus-theme-search-typesense【typesense搜索组件 https://github.com/typesense/docusaurus-theme-search-typesense】
################# 网站搜索【typesense-docsearch】 ################# -
本地搜索【docusaurus-search-local】
//////////////////////////////// 网站搜索【docusaurus-search-local】 ///////////////////////////////
// docusaurus-search-local项目地址: https://github.com/easyops-cn/docusaurus-search-local
// 官方介绍: https://www.wangshenwei.com/multilingual-full-text-search
// 步骤1 安装docusaurus-search-local库: npm install --save @easyops-cn/docusaurus-search-local
// 步骤2 配置“docusaurus-search-local”插件
// 步骤3 打包发布项目 看效果
themes: [
[
require.resolve("@easyops-cn/docusaurus-search-local"),
/** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */
({
hashed: true, // `hashed` is recommended as long-term-cache of index file is possible.
language: ["en", "zh"], // For Docs using Chinese, it is recomended to set
// If you're using `noIndex: true`, set `forceIgnoreNoIndex` to enable local index:
// forceIgnoreNoIndex: true,
}),
],
],
//////////////////////////////// 网站搜索【docusaurus-search-local】 /////////////////////////////// -
本地搜索【docusaurus-lunr-search】
//////////////////////////////// 网站搜索【docusaurus-lunr-search】 ///////////////////////////////
// docusaurus-lunr-search项目地址: https://github.com/praveenn77/docusaurus-lunr-search
// 步骤1 安装docusaurus-lunr-search库: npm i docusaurus-lunr-search --save
// 步骤2 安装lunr库(如果npm list发现没有安装lunr): npm i lunr --save
// 步骤3 配置“docusaurus-lunr-search”插件
// 步骤4 打包发布项目 看效果
// 配置“docusaurus-lunr-search”插件:
// 配置A（默认只支持en）
// plugins: [require.resolve('docusaurus-lunr-search')],
// 配置B（支持zh和en）
plugins: [[ require.resolve('docusaurus-lunr-search'), {
languages: ['en', 'zh'] // language codes,
}]],
// 目前能支持的语言列表【https://github.com/MihaiValentin/lunr-languages】
// 加上zh后报错: “[ERROR] Error: Unable to build website for locale en.” [cause]: Error: Cannot find module '@node-rs/jieba'
// 解决办法: 安装jieba【npm i @node-rs/jieba --save】
//////////////////////////////// 网站搜索【docusaurus-lunr-search】 ///////////////////////////////
mkdocs建站
参考
Mac Homebrew 安装
#安装pip和python (由于本地有很多python版本，改用安装pipx)
brew info pipx
brew install pipx
#安装mkdocs
pipx install mkdocs
pipx list
#使用mkdocs前，将mkdocs添加到当前会话的临时环境变量中（用的时候添加）
export PATH="/Users/zhoujh/.local/bin:$PATH"
#确认mkdocs是否可用
mkdocs --version
ubuntu 安装
#安装python
$ python3 --version
$ apt show python3
$ apt install python3
#安装pip
$ which pip
$ apt show python3-pip
$ apt install python3-pip
$ pip --version
#安装pip
$ pip show mkdocs
$ pip install mkdocs --break-system-packages
$ pip show mkdocs-literate-nav
$ pip install mkdocs-literate-nav --break-system-packages
$ pip list
mkdoc 使用
# 创建项目
$ mkdocs --help
$ mkdocs new s-tech
# debug
$ cd s-tech
$ mkdocs serve
# debug 配置nginx 转发
$ vim /etc/nginx/sites-enabled/mkdocs.debug.proxy.conf
server {
listen 3081;
listen [::]:3081;
server_name _;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
# build打包
$ mkdocs build
Docusaurus 特色用法
提示
tip
Some content with Markdown syntax. Check this api.
代码块添加标题
/src/components/HelloCodeTitle.js
function HelloCodeTitle(props) {
return <h1>Hello, {props.name}</h1>;
}
高亮指定的行
function HighlightSomeText(highlight) {
if (highlight) {
return '这行被高亮了！';
}
return '这里不会';
}
function HighlightMoreText(highlight) {
if (highlight) {
return '这块被高亮了！';
}
return '这里不会';
}
显示行号
import React from 'react';
function MyComponent(props) {
if (props.isBar) {
return <div>Bar</div>;
}
return <div>Foo</div>;
}
export default MyComponent;
多种编程语言代码块
常用命令
Mouse over the windows toolbar will make word count visible. "Always show word count" can be set from preference panel. Click it will popup detailed word count tooltip. If a range of text is selected word count for selection will also be displayed on word count tooltip.
MySQL
Mouse over the windows toolbar will make word count visible. "Always show word count" can be set from preference panel. Click it will popup detailed word count tooltip. If a range of text is selected word count for selection will also be displayed on word count tooltip.
Centos和Ubuntu 安装配置
Mouse over the windows toolbar will make word count visible. "Always show word count" can be set from preference panel. Click it will popup detailed word count tooltip. If a range of text is selected word count for selection will also be displayed on word count tooltip.
极空间安装配置
Mouse over the windows toolbar will make word count visible. "Always show word count" can be set from preference panel. Click it will popup detailed word count tooltip. If a range of text is selected word count for selection will also be displayed on word count tooltip.
php学习笔记
Mouse over the windows toolbar will make word count visible. "Always show word count" can be set from preference panel. Click it will popup detailed word count tooltip. If a range of text is selected word count for selection will also be displayed on word count tooltip.