变革是不可避免的,它偶尔会出现。 在过去的几年里,有一些变革是强加给我们的,变革是我们无法直接控制的。 但是在Layer0/Edgio,最近的变化是我们自己做的,这是非常需要的:对Edgio文档进行完全重写和重新设计。
这项大修旨在是基础和可控的。 事实是,我们想把事情交到我们自己手中,就像我们以前从未做过的那样。 ,深受React beta文档的启发,我们通过创建一个基本repo实例并针对我们的特定用例对其进行微调,在巨人的肩膀上进行了阐述
第一件事
第一步是反作用不和谐通道。 简而言之，社区帮助确定了React的beta文档回购。
React beta repo作为一个领先的开端
我们花了几天时间研究React docs beta站点是如何构建的，它使用了哪些技术，以及如何利用和构建此堆栈来满足我们的特定需求。 我们对MDX和Next.js的预感是对的,我们发现自己是一个领先的开端。
技术
以下是使用的一些主要技术：
- MDX：具有嵌入式React组件的功能性标记
- next.js: React framework
- Webpack：模块捆绑程序
- 样式化组件：样式化
- 阿尔及利亚：搜索
- 棱镜：代码语法突出显示
MDX: MDX是组件时代Markdown的扩展形式。 它允许您在任何Markdown文档中嵌入JSX ,将带有Markdown的内容创作提升到一个新的水平,从而使Markdown发挥作用。
我们已经从MDX，秘密组件和前端文档，样式指南和MDX的崛起等文章中了解了MDX是什么以及它有多强大。 这为我们创建的一些自定义组件铺平了道路。
next.js:将MDX与Next.js配对并不新鲜,所以第一个本能就是阅读官方文档或这篇博客文章。 有几种方法可以将markdown导入到Next.js页面中,例如拥有本地markdown文档,并使用getStaticProps，getStaticPaths或getServerSideProps中的remark和remark-html等包将其转换为HTML
另一种方法是使用@next/MDX包将`.md `或`.mdx `文件直接定义为Next.js页面,或者如果您想处理较低级别的内容,请遵循React的团队方法和DIY。
webpack: next.config.js (或next.config.mjs)由next.js服务器和构建阶段使用。在这里,您可以为高级用例配置next.js ,例如让markdown读取Pages目录中的`.mdx`文件扩展名,并将它们作为Next.js页面加载。
Webpack使用加载器预处理文件。其中一个较常见的使用案例是Transspiling,其中一个常见的软件包是Babel-loader (使用Babel加载ES2015+代码并使用Transspiles到ES5 )。要在Next.js中加载Webpack的`. mdx`文件,请使用@mdx-js/loader。
@mdx-js/loader可以请求帮助remark/rehype插件的丰富生态系统Markdown到html的细粒度转换。
Styled Components:虽然在Next.js中编写CSS的方法过多,但我们选择了Styled Components。 借助Styled Components,我们能够以更协调，模块化，耦合和更少侵入的方式创作组件样式。 了解如何在React中使用Styled-Components，或探索Styled-components Happy Path，了解有关Styled-Components的更多信息。
Algolia：我们已升级到最新版本的DocSearch v3，该版本构建在Algolia AutoComplete之上，增强了可访问性和响应性，可在台式机和移动设备上提供更流畅的体验。 加上这是Algolia Crawler在执行搜索时提取最相关的信息。
PRISM: PRISM: PRISM是久经考验和值得信赖的代码语法突出显示符。 它不仅易于入门,它还具有丰富的插件生态系统,并可扩展为主题等操作的明智默认值。
功能
虽然重新设计的面值有很大的外观变化，但还有其他特征，例如：
一个有重要细节的新主页
开始使用Layer0/Edgio平台的四大支柱,构建自己的方式,并进入Layer0/Edgio提供的更多功能。
主题
只需单击按钮即可在主题之间切换。 从亮模式转到暗模式，反之亦然，或者让您的操作系统决定。
改进的导航
两种主要导航模式—菜单(左侧)和目录(右侧)—经过重新设计，可以更好地导航和扫描。 新的分页控件(位于底部)可帮助您了解哪个集是下一个集，哪个集是前一个集。
改进的编码块
使用PrismJS，语法突出显示和自定义非常简单。
改进的搜索
阿尔及利亚搜索已升级到v3，使我们可以更好地控制将哪些内容编入结果索引。 这也适用于移动设备。
但等一等,还有更多
React beta docs repo有很多工作要做，我们已经能够在这里利用开源的强大功能。 有一些东西,我们几乎得到了盒子,像目录,文档分页,面包屑,SEO等. 其中一些我们已经进行了调整，以更好地服务于我们的环境，还有一些我们仍在探索。
贡献
对我们来说,这是新文档是朝着正确方向迈出的一步,也是新开端的开始。 我们希望您加入我们的旅程，因为我们将继续帮助您在不影响开发人员体验的前提下，使您的网站更快，更安全。 Layer0开发者文档的源代码位于GitHub上的一个开放存储库中,我们欢迎您提供反馈和拉取请求。 如果您发现了一个拼写错误或更好的解释方式，请提交一个拉取请求或提出一个问题！ 另请参阅我们的贡献指南。
