Home 技术文章 新的Layer0 (Edgio)文档是新开始的开始
Applications

新的Layer0 (Edgio)文档是新开始的开始

About The Author

Outline

改变是不可避免的,而且每一次都在发生。 在过去几年里,我们不得不面对一些变化,这些变化是我们无法直接控制的。 但在Layer0/Edgio,最近的变化是我们自己所做的事情之一,这是非常需要的:对Edgio文档进行完全的重写和重新设计。

这一大修旨在成为基础和可控的。 事实是,我们想像我们以前从未做过的那样,把事情交给我们自己。 因此,在React beta文档的极大启发下,我们在巨人的肩膀上创建了一个基础repo的实例,并针对我们的特定用例对其进行微调。‍

首先要做的事情

第一个步骤是反应不和通道。 简单地说,社区帮助识别React的测试文档repo。

React beta repo作为一个开端

我们花了几天时间研究React docs测试网站是如何构建的,它使用什么技术,以及我们如何利用和构建此堆栈以满足我们的特定需求。 我们对MDX和Next.js的预感是正确的,我们发现自己有一个开端。

技术

以下是使用的一些主要技术:

  • MDX:嵌入式React组件的功能性标注
  • next.js:React框架
  • webpack:模块打包器
  • 造型组件:造型
  • 阿尔戈利亚:搜索
  • 棱镜:代码语法突出显示

MDX: MDX是组件时代Markdown的扩展形式。 它允许您将JSX嵌入任何Markdown文档中,将内容创作与Markdown提升到一个新的水平,从而使Markdown功能发挥作用。

我们已经从MDX,其秘密成分和前端文档,风格指南和MDX的崛起等文章中了解了MDX是什么以及它的强大功能。 这为我们创建的一些自定义组件铺平了道路。

next.js :将MDX与next.js 配对不是什么新东西,所以第一个本能是阅读官方文档或这篇博客文章。 有几种方法可以将标记转入Next.js页面,例如,在getStaticPros,getStaticPaths或getServerSideProps中使用remark和remark-html等软件包将本地标记文档转换为HTML

另一种方法是将`.md `或`.mdx`文件直接定义为带有@next/mdx包的Next.js页面,或者如果您喜欢处理低级内容,请遵循React的团队方法和DIY。

webpack: next.config.js (或next.config.mjs)由Next.js服务器和构建阶段使用。 您可以在这里为高级用例配置Next.js,例如让Markdown读取Pages目录中的`.mdx`文件扩展名,并将其加载为Next.js页。

Webpack使用加载器来预处理文件。 其中一个比较常见的用例是转置,其中一个常见的软件包是Babel-loader(使用Babel将ES2015代码和转置文件加载到ES5 )。 要使用Next.js中的webpack加载`.mdx`文件,请使用@mdx-js/loader。

Remark/rehype插件的丰富生态系统可以通过@mdx-js/loader请求帮助,以实现Markdown到html的精细纹理转换。

样式组件: 虽然在Next.js中编写CSS的方法很多,但我们选择了样式组件。 使用Styled Components,我们能够以更加协同,模块化,耦合和更少干扰的方式创作组件样式。 了解如何在React中使用Styled-Components,或探索Styled-Components欢乐之路,了解有关Styled Components的更多信息。

Algolia: 我们升级到了最新版本的DocSearch v3,该版本构建在Algolia AutoComplete之上,增强了可访问性和响应性,使台式机和移动设备上的体验更加流畅。 与之相结合的是Algolia Crawler,可在执行搜索时提取最相关的信息。

Prism: Prism是经过测试和信任的代码语法荧光笔。 它不仅更容易入门,它还具有丰富的插件生态系统,并可通过合理的默认值来扩展,用于像主题化这样的操作。

功能

虽然重新设计的主要特征是表面价值的外观变化,但还有其他特征,例如:

一个新的主页与重要的细节

开始使用Layer0/Edgio平台的四大支柱,并构建Layer0/Edgio提供的更多功能。

主题

只需单击按钮即可在主题之间切换。 从浅色模式切换到深色模式,反之亦然,或者由您的操作系统决定。

改进的导航

两种主要导航模式—菜单(左侧)和目录(右侧)—经过重新设计,可更好地进行导航和扫描。 新的分页控件(位于底部)可帮助您了解下一个指南和前一个指南。

改进的代码块

使用PrismJS,语法突出显示和自定义非常简单。

改进的搜索功能

Algolia搜索已升级到v3,这使我们能够更好地控制为结果编制索引的内容。 这也适用于移动设备。

但等待,还有更多

React beta docs repo有很多优点,我们能够在这里充分利用开放源代码的强大功能。 有一些东西,我们得到几乎开箱,如目录,文档分页,面包屑,搜索引擎优化等. 其中一些我们已经调整以更好地服务于我们的环境,还有一些我们仍在探索。

贡献

对我们来说,这是新的文件是朝着正确方向迈出的一步,也是一个新开端的开始。 我们希望您加入我们的行列,因为我们将继续帮助您在不影响开发人员体验的情况下,使您的网站更快,更安全。 Layer0开发人员文档的源代码位于GitHub上的一个开放存储库中,我们欢迎您提供反馈和提交请求。 如果您发现了拼写错误或更好的解释方式,请提交拉取请求或提交问题! 另请参阅我们的贡献指南。