2 posts tagged with "以内容为中心的静态网站"

1. 路由​

• 在 /src/pages/ 目录下所创建的任何 JavaScript/TypeScript 文件都会自动生成相应的网站路径

/src/pages/index.js → [baseUrl]
/src/pages/foo.js → [baseUrl]/foo
/src/pages/foo/test.js → [baseUrl]/foo/test
/src/pages/foo/index.js → [baseUrl]/foo/

• 默认情况下，以 开头的任何 Markdown 或 Javascript 文件都会被忽略，也不会为其生成任何路由（参见 exclude 选项，默认情况下，以 开头的文件、测试文件 (.test.js) 和 __tests__ 目录内的文件不会被转换成页面）。
• 如果你不小心创建映射到同一路由的多个页面，你只能访问最后创建的页面，而其他的冲突页面会被覆盖。 要解决此问题，你需要编辑或移除重复的路由。

2. 文档​

2.1 文档的url​

• 默认为它相对于 docs 文件夹的路径，如/docs/Docusaurus笔记
• 可以使用slug自定义文档url，slug 会被添加到文档插件的 routeBasePath 后面。routeBasePath 默认是 /docs。

2.2 目录​

如果你需要更改显示的标题范围，你可以自定义最小和最大的标题级别——既可以按页配置，也可以全局设置目录标题级别。

"tableOfContents.minHeadingLevel" must be greater than or equal to 2

2.3 页面片段​

在 docs 目录下所有带有下划线（_）前缀的文件都会被当作页面「片段」，并被默认忽略。

2.4 标签​

使用tags为文档创建标签

tags:
  - 演示
  - 开始上手

// 或者
tags: [演示, 开始上手]

2.5 侧边栏​

• sidebar_position设置相对位置
• sidebar_label设置label
• sidebar_class_name设置className
• sidebar_custom_props设置customProps
• 可以用 pagination_next 和 pagination_prev 自定义分页导航

2.6 文档id​

• 每个文档均有唯一的 id（标识符）。 默认情况下，文档 id 是文件相对文档根目录(docs)的路径（不包括后缀）。
• 可以在前言中指定 id 的最后一部分。注意：前面还是相对路径，比如：docs/guide/hello.md 指定id: part1，则其最终的 id 则为 guide/part1。

3. blog​

• 博客日期可以写在标题里，或者使用前言，如：

---
date: 2021-09-13T10:00
---

---
date: 2021-09-13T18:00
---

4. markdown​

| <div style="width:100px">属性</div> | 说明 | 类型 | <div style="width:100px">默认值</div> |
| --- | --- | --- | --- |
| fill | 填充模式 | `boolean` | `false` |

4.1 Markdown可以嵌入HTML标签​

### Details element example

<details>
  <summary>Toggle me!</summary>
  <div>
    <div>This is the detailed content</div>
    <br/>
    <details>
      <summary>
        Nested toggle! 内含惊喜……
      </summary>
      <div>
        😲😲😲😲😲
      </div>
    </details>
  </div>
</details>

在 Markdown 中，如果你想在表格的单元格中展示多行内容，你需要使用 <br> 标签来实现换行。Markdown 本身不直接支持在表格单元格内使用回车换行，但 HTML 标签可以帮助你实现这个效果。

| 列1       | 列2            | 列3       |
|-----------|----------------|-----------|
| 单元格1   | 单元格2<br>换行| 单元格3   |
| 单元格4   | 单元格5<br>换行| 单元格6   |

4.2 MDX​

• Docusaurus 原生支持 MDX v1，可以直接在 Markdown 文档中编写 JSX，并渲染为 React 组件。

• 可以用MDX 实时编辑器 检验你写的mdx是否正确。（MDX is not 100% compatible with CommonMark. ）

• 要在 MDX 文件中自定义组件，你必须导出它：只有以 export 开头的段落才会被解析为组件，而不是文本。

export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '2px',
      color: '#fff',
      padding: '0.2rem',
    }}>
    {children}
  </span>
);

<Highlight color="#25c2a0">Docusaurus 绿</Highlight> 和 <Highlight color="#1877F2">Facebook 蓝</Highlight> 是我最喜欢的颜色。
我可以把我的 _JSX_ 和 **Markdown** 写在一起！

• 可以使用import导入组件

  caution

  import语句 与下面的内容 之间要空出一行

• 除了导入组件和导出组件，第三种在 MDX 中使用组件的方式是把它注册到全局作用域，这样它将自动在每个 MDX 文件中可用，无需任何导入声明。如：在src/theme/MDXComponents中声明好underline后可以在每个文件里自由使用 <underline> 了，不需要写导入语句。

5. 内置组件​

5.1 Layout​

• title 用于设置document.title 页面标题
• description 用于在设置meta <meta name="description" content="description这个prop的值" data-rh="true">

5.2 Tabs​

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="apple" label="苹果" default>
    这是个苹果 🍎
  </TabItem>
  <TabItem value="orange" label="橙子">
    这是个橙子 🍊
  </TabItem>
  <TabItem value="banana" label="香蕉">
    这是个香蕉 🍌
  </TabItem>
</Tabs>

5.3 CodeBlock​

5.4 TOCInline​

每个 Markdown 文档会在右上角显示一个目录栏。 但也可以通过 TOCInline，直接在 Markdown 文档中显示一个内联目录。

import TOCInline from '@theme/TOCInline';


<TOCInline
  // 只显示 h2 和 h4 标题
  toc={toc.filter((node) => node.level === 2 || node.level === 4)}
  minHeadingLevel={2}
  // 除了默认的 h2 和 h3 标题，也把 h4 标题包含进来
  maxHeadingLevel={4}
/>

6. 代码块​

• 支持的语言有：

  • markup: true,
  • bash: true,
  • clike: true,
  • c: true,
  • cpp: true,
  • css: true,
  • "css-extras": true,
  • javascript: true,
  • jsx: true,
  • "js-extras": true,
  • "js-templates": true,
  • coffeescript: true,
  • diff: true,
  • git: true,
  • go: true,
  • graphql: true,
  • "markup-templating": true,
  • handlebars: true,
  • json: true,
  • less: true,
  • makefile: true,
  • markdown: true,
  • objectivec: true,
  • ocaml: true,
  • python: true,
  • reason: true,
  • sass: true,
  • scss: true,
  • sql: true,
  • stylus: true,
  • tsx: true,
  • typescript: true,
  • wasm: true,
  • yaml: true,

• 你可以用 highlight-next-line、highlight-start、highlight-end 等注释来选择要高亮的行。

• 可以使用title设置代码块的title

• 可以使用showLineNumbers开启行数显示

• 交互式代码编辑器

  由React Live驱动

  • npm install --save @docusaurus/theme-live-codeblock
  • 配置docusaurus.config.js

module.exports = {
  // ...
  themes: ['@docusaurus/theme-live-codeblock'],
  // ...
};

• 要使用此插件，只需要创建一个代码块，同时在语言元标签中加上 live

Live Editor

function Clock(props) { const [date, setDate] = useState(new Date()); useEffect(() => { var timerID = setInterval(() => tick(), 1000); return function cleanup() { clearInterval(timerID); }; }); function tick() { setDate(new Date()); } return ( <div> <h2>现在是 {date.toLocaleTimeString()}。</h2> </div> ); }

function Clock(props) {
  const [date, setDate] = useState(new Date());
  useEffect(() => {
    var timerID = setInterval(() => tick(), 1000);
    return function cleanup() {
      clearInterval(timerID);
    };
  });
  function tick() {
    setDate(new Date());
  }
  return (
    <div>
      <h2>现在是 {date.toLocaleTimeString()}。</h2>
    </div>
  );
}

Result

Loading...

7. Admonitions 告示​

• :::note :::
• :::tip :::
• :::info :::
• :::caution :::
• :::danger :::

8. 插件​

Using TailwindCSS v3 in Docusaurus in 5 steps

• npm install -D tailwindcss postcss autoprefixer
• npx tailwindcss init
• 创建一个自定义插件

plugins: [
  async function myPlugin(context, options) {
    return {
      name: "docusaurus-tailwindcss",
      configurePostCss(postcssOptions) {
        // Appends TailwindCSS and AutoPrefixer.
        postcssOptions.plugins.push(require("tailwindcss"));
        postcssOptions.plugins.push(require("autoprefixer"));
        return postcssOptions;
      },
    };
  },
],

• 修改src/css/custom.css
• 然后使用tailwind css，发现会影响docusaurus原有样式

如何在 Docusaurus 中引入 TailwindCSS

• npm install --save-dev postcss-nested
• 修改src/css/custom.css，把tailwindcss的基础样式放在.tailwind中，使用 postcss-nested，这样可以把 tailwind 的样式限制在带有 tailwind class 的容器中，不会干扰 docusaurus 已有的样式
• 在所有需要用 tailwind 写样式的部分，就在最外层容器加一个 className="tailwind" 即可生效
• 可以不影响docusaurus原有样式使用tailwindcss了，但是控制台有warning： No serializer registered for Warning，这个warning咋解决？虽然不影响，但是有点强迫症😂

一、使用过程中遇到的问题​

参考：在项目中使用 vuepress 搭建组件文档踩坑

1. 使用scss​

1. npm install -D node-sass sass-loader
2. 启动报错，高版本的node-sass，sass-loader与 vuepress 版本并不兼容，可行的版本是：node-sass@4.14.1，sass-loader@7.3.1。

2. 引入组件库​

以element-ui为例

1. npm install element-ui
2. 使用enhanceApp.js

// 示例
export default ({
  Vue, // VuePress 正在使用的 Vue 构造函数
  options, // 附加到根实例的一些选项
  router, // 当前应用的路由实例
  siteData // 站点元数据
}) => {
  // ...做一些其他的应用级别的优化
}

// 使用
// docs/.vuepress/enhanceApp.js
import Element from 'element-ui';
import 'element-ui/lib/theme-chalk/index.css';

export default ({ Vue, options, router }) => {
  Vue.use(Element);
};

3. 上面引入组件库后打包报错：window is not defined

   info

   vuepress是如何工作的:

   • 一个 VuePress 网站是一个由 Vue、Vue Router和 webpack 驱动的单页应用。
   • 在构建时，vuepress会为应用创建一个服务端渲染（SSR）的版本，然后通过虚拟访问每一条路径来渲染对应的HTML。

import 'element-ui/lib/theme-chalk/index.css';

export default async ({ Vue, options, router, isServer }) => {
  if (!isServer) { // 客户端
    let Element = await import('element-ui');
    Vue.use(Element.default);
  }
}

// 使用async-await，避免异步加载第三方依赖包，导致页面渲染会出错

4. 引入组件库后启动报错：Cannot find module 'core-js/library/fn/xxx/xxx'

   原因应该是 UI 组件中依赖的core-js包和 vuepress 所依赖的core-js包版本不兼容造成的。

// 配置chainWebpack解决该问题
// docs/.vuepress/config.js

chainWebpack: config => {
  config.resolve.alias.set('core-js/library/fn', 'core-js/features')
},

二、主题theme​

1. 继承主题​

假设你想创建一个继承自 VuePress 默认主题的派生主题，你只需要在你的主题配置中配置 extend 选项：

// .vuepress/theme/index.js
module.exports = {
  extend: '@vuepress/theme-default'
}

2. 组件覆盖​

• 父主题的所有能力都会"传递"给子主题，对于文件级别的约定，子主题可以通过在同样的位置创建同名文件来覆盖它
• 子主题可以通过@theme 别名访问父主题的组件，比如：当子主题中有Navbar.vue时，如下：

theme
└── components
    └── Navbar.vue