Choppy documentation website. http://docs.3steps.cn
Du kan inte välja fler än 25 ämnen Ämnen måste starta med en bokstav eller siffra, kan innehålla bindestreck ('-') och vara max 35 tecken långa.
YJC 4329a98f65 增加插件文档 11 månader sedan
docs 增加插件文档 11 månader sedan
website 增加插件文档 11 månader sedan
.dockerignore First commit. 1 år sedan
Dockerfile First commit. 1 år sedan
README.md 增加插件文档 11 månader sedan
docker-compose.yml 修改custom.css等 1 år sedan
package.json First commit. 1 år sedan
yarn.lock First commit. 1 år sedan

README.md

用户指南

克隆choppy-docs

git clone http://choppy.3steps.cn/go-choppy/choppy-docs.git

目录介绍

  • 文档源文件:包含可编写的 Markdown 文件的文件夹 choppy-docs/docs
  • 博客:包含了可编写的 Markdown 文章的文件夹 choppy-docs/website/blog
  • 页面:包含示例网站顶级页面的文件夹 choppy-docs/website/pages
  • 静态资源与图片:包含供网站使用的静态资源文件夹 choppy-docs/website/static

关键文件

切莫删除或修改 choppy-docs/website/siteConfig.js 和 choppy-docs/website/core/Footer.js 文件

  • 文档目录:choppy-docs/website/sidebars.json 文件包含文档文件的结构与排序,十分关键,所有文档源文件都需要记录到此文件才能够正常渲染出文档目录
  • 页脚:choppy-docs/website/core/Footer.js 文件是一个 React 组件,用于生成 choppy-docs 站点的页脚,它可以由用户定制
  • 配置文件:choppy-docs/website/siteConfig.js 文件是 choppy-docs 的主配置文件

修改文档/Blog

Docs撰写

所有文档位于choppy-docs/docs目录,撰写规范如下:

  • 将您的文档以 .md 文件的形式添加到 /docs 文件夹中,并确保每个文件都有正确的header。 最简单的标题如下,其中 id 是链接名称(例如 docs/intro.html),title 当然是浏览器页面的标题

    ---
    id: intro
    title: 入门
    ---
    
  • 将零个或多个文档添加到 sidebars.json 文件,以便您的文档在侧边栏中呈现,如果您想要显示它们

    如果您不将文档添加到 sidebars.json 文件中,那么文档依然被渲染,但只能从其他文档链接到该文档,并使用已知的URL进行访问

    注意:sidebars.json文件中填写的均是id,而非 Markdown 文件名。sidebars.json文件依靠id来索引 Markdown 文件。

  • 示例:

    {
      "docs": {
          "Choppy 简介": ["choppy-intro"],
          "快速指南": ["quick-intro"],
          "Cromwell": [],
          "WDL 定义": ["wdl/wdl-intro"],
          "Choppy App定义": [
              "choppy_app/choppy-app-intro",
              "choppy_app/choppy-app-vars",
              "choppy_app/choppy-app-expression",
              "choppy_app/choppy-app-filter",
              "choppy_app/choppy-app-whitespace",
              "choppy_app/choppy-app-condition",
              "choppy_app/choppy-app-annotation"
          ]
    }
    

Blog撰写

位于choppy-docs/website/blog目录

  • 添加博文

    要在博客中发布,请在博客文件夹中创建一个格式为 YYYY-MM-DD-My-Blog-Post-Title.md 的文件。 发布日期是从文件名中提取的。例如,在 website/blog/2017-08-18-Introducing-Docusaurus.md:

    ---
    author: Frank Li
    authorURL: https://twitter.com/foobarbaz
    authorFBID: 503283835
    title: Introducing Docusaurus
    ---
    
  • Header 参数

    唯一必需的字段是title; 不过,我们也提供了将作者信息添加到博客文章的参数。

    • author - 作者署名的文本标签。
    • authorURL - 与作者相关的网址。 这可能是一个Twitter,GitHub,Facebook帐户等。
    • authorFBID - 用于提取个人资料图片的 Facebook ID。
    • title - 博客文章标题。
  • 摘要截断

    使用博客文章中的 标记来表示在查看博客发布的所有博客文章时将显示的摘要。 在 之上的任何内容都将成为摘要的一部分。 例如:

    ---
    title: 截断示例
    ---
    
    所有这些将成为博客文章摘要的一部分。
        
    就到这里。
        
    <!--truncate-->
        
    但是从此以后的任何内容都不会是。
        
    不是这里。
        
    也不是这里。
    

启动文档 Server

# 切换工作目录
cd ./website

# 安装依赖环境
yarn install

# 启动 dev-server
yarn start

# build 静态网站
yarn build

# 构建并上传至阿里云OSS
yarn build && yarn upload

FAQ

  1. Cannot GET /

    通常由于 Docusaurus 无法正确解析sidebars.json 文件所致。比如 id 引用不正确或者不是一个合格的markdown文件