`NextJs` 搭建类语雀文档网站（一）

NextJs 搭建类语雀文档网站（一）

需求背景

我们门户网站需要一个承载一个文档，用来介绍一些我们公司的产品等，产品其实给的是world文档，那对于我们来说，要嵌入到我们自己的门户网站，其实有很多办法，做成网页，做成富文本，或者通过三方插件直接加载pdf，world 文件即可，这种都可以实现，但是，我们通过调研，发现有一个产品和 NextJs 比较契合，虽然没有使用过，但是看着还不错，就决定使用该产品（舍我其谁，总要有人先吃这个螃蟹🦀）

Nextra

Nextra 是一个基于 Next.js 的静态网站生成器，它提供了丰富的主题和功能，可以轻松创建一个具有文档、博客、API 文档、导航栏、侧边栏、主题切换，多语言，搜索等功能的网站。当然他支持 Tailwind CSS，以及可以在app router中使用，不过目前只支持page router，下面是官方给的解决方案

Can I use Nextra with Next.js app router?

No, Nextra only works with the /pages directory at the moment. Support for the app router has not been implemented yet. But you can use /app and /pages at the same time - just put your docs inside /pages and your other routes in /app

总结一下就是在app router中把md文件放到pages目录下面去

介绍

Nextra blogsTheme 和 docsTheme ，这两种对应不同的风格和配置，需要根据不同theme的不同，配置项略微不同；上面👆两个风格的在线地址，可以查看具体风格。以下是两种风格的截图参考。

BlogsTheme

DocsTheme

1，安装（这里以docs为例）

next react react-dom 可以不用安装，因为next已经安装了，直接安装 nextra nextra-theme-blog 即可

yarn add nextra nextra-theme-blog

2，配置Blog Theme Config

创建blogs的theme.config.jsx 文件，

export default {
  footer: <p>MIT 2023 © Nextra.</p>,
  head: ({ title, meta }) => (
    <>
      {meta.description && (
        <meta name="description" content={meta.description} />
      )}
      {meta.tag && <meta name="keywords" content={meta.tag} />}
      {meta.author && <meta name="author" content={meta.author} />}
    </>
  ),
  readMore: 'Read More →',
  postFooter: null,
  darkMode: false,
  navs: [
    {
      url: 'https://github.com/shuding/nextra',
      name: 'Nextra'
    }
  ]
}

3，配置Next.js Config

const withNextra = require('nextra')({
  theme: 'nextra-theme-blog',
  themeConfig: './theme.config.jsx'
})
 
module.exports = withNextra({})

4，路由

pages
    |
    |_index.mdx
    |_about.mdx
    |_blog
      |_test1
        |_test.mdx
        |_nextjs.mdx
      |_test2
        |_world.mdx
        |_nextjs.mdx

到此，基本的配置就已经完成了，路由规则是按照nextJs的规则生成的，直接按照文件路径访问即可；

4.1 自定义路由

nextra 支持自己自定义路由的规则配置，只需要在当前路径下面添加一个_meta.json 文件，既可以指定自定义规则

pages
    |__meta.json
    |_index.mdx
    |_about.mdx
    |_blog
      |_test1
        |_test.mdx
        |_nextjs.mdx
        |__meta.json
      |_test2
        |_world.mdx
        |_nextjs.mdx
        |__meta.json

_meta.json

{
  "index": "My Homepage",
  "about": "About Us"
}

最基本的nextra 就已经全部配置完成了，当然，如果项目里面还有i18n国际化的需求，需要去配置对应的多语言文件，我们下期再介绍。

写在最后

如有错误，欢迎大家指正。