A mudança é inevitável, e de vez em quando surge. Nos últimos anos, há mudanças que nos foram forçadas, mudanças sobre as quais não tínhamos controlo direto. Mas no Layer0/Edgio, a mudança recente é de nossa própria criação, uma que era muito necessária: Uma reescrita completa e redesenho da documentação do Edgio.
Esta revisão foi feita para ser fundamental e controlável. A verdade é que queríamos levar as coisas às nossas próprias mãos como nunca fizemos antes. E assim, fortemente inspirados nos documentos beta do React, nós nos propomos sobre os ombros de gigantes criando uma instância do repositório base e ajustando-a para o nosso caso de uso específico.
Primeiro, as primeiras coisas
O primeiro passo foi o canal Discórdia Reactiflux. Simplificando, a comunidade ajudou a identificar o repositório de documentação beta do React.
O repo beta do React como um começo de cabeça
Passámos alguns dias a investigar como foi construído o site beta da React docs, que tecnologias utiliza e como podemos aproveitar e construir sobre esta pilha para satisfazer as nossas necessidades específicas. O nosso palpite sobre o MDX e o Next.js estava certo e nos encontrámos com um ponto de partida.
Tecnologias
Aqui estão algumas das principais tecnologias utilizadas:
- MDX: Marcação funcional com componentes React incorporados
- Next.js: Reaja framework
- Webpack: Agrupamento de módulos
- Componentes estilizados: Estilo
- Algolia: Pesquisar
- Prisma: Realce da sintaxe do código
MDX: MDX é uma forma estendida de Markdown para a era dos componentes. Isso torna o markdown funcional permitindo que você incorpore o JSX em qualquer documento de markdown, levando a criação de conteúdo com markdown a um novo nível.
Já sabíamos o que era o MDX e quão poderoso pode ser de artigos como o MDX, o ingrediente secreto e a documentação de front-end, os guias de estilo e a ascensão do MDX. Isto abriu caminho para alguns dos componentes personalizados que criámos.
Next.js: Combinar o MDX com o Next.js não é algo novo, então o primeiro instinto foi ler a documentação oficial ou este post no blog. Existem algumas abordagens para obter o markdown nas páginas do Next.js, como ter um documento markdown local e transformá-lo em HTML usando pacotes como remark e remark-html dentro de um dos getStaticProps, getStaticPaths ou getServerSideProps
Outra abordagem é definir um arquivo .md ou mdx diretamente como páginas Next.js com o pacote seguinte/mdx, ou se você gosta de lidar com as coisas de nível inferior, siga a abordagem da equipe do React e DIY.
Webpack: Next.config.js (ou next.config.mjs) é usado pelo servidor Next.js e fases de compilação. É aqui que você pode configurar Next.js para casos de uso avançados, como deixar markdown ler extensões de arquivo .mdx no diretório Páginas e carregá-las como páginas Next.js.
O Webpack usa carregadores para pré-processar arquivos. Um dos casos de uso mais comuns é a transpiação e um desses pacotes comuns é o babel-loader (carrega código ES2015 e transpila para ES5 usando Babel). Para carregar arquivos .mdx com o Webpack no Next.js, é usado o mdx-js/loader.
O rico ecossistema de plug-ins de observação/rehype pode ser chamado para obter ajuda por mdx-js/loader para uma transformação de grão fino de markdown para html.
Componentes estilizados: Embora haja uma infinidade de maneiras de escrever CSS no Next.js, escolhemos componentes estilizados. Com componentes estilizados, somos capazes de criar estilos de componentes de uma forma mais colocada, modular, acoplada e menos intrusiva. Saiba como usar componentes estilizados no React ou explore o Happy Path dos componentes estilizados para obter mais informações sobre componentes estilizados.
Algolia: Atualizámos para a versão mais recente do DocSearch v3, que é construído sobre o Algolia Autocomplete, fornecendo melhorias na acessibilidade e capacidade de resposta, proporcionando uma experiência mais suave tanto em computadores como em dispositivos móveis. Juntamente com isso está o Algolia Crawler para extrair a informação mais relevante ao realizar a sua pesquisa.
Prisma: Prisma é o marcador de sintaxe de código bem testado e confiável. Não é apenas mais fácil começar, mas também tem um ecossistema rico de plug-ins, e é extensível com padrões razoáveis para operações como o theming.
Características
Embora o redesenho tenha uma grande mudança estética no valor facial, existem outras caraterísticas como:
Uma nova página inicial com detalhes importantes
Comece com os quatro pilares da plataforma Layer0/Edgio e construa o seu caminho para cima e para dentro de mais recursos que Layer0/Edgio tem para oferecer.
Theming
Alternar entre temas está apenas a um clique de distância. Passe do modo claro para o modo escuro ou vice-versa ou deixe o seu sistema operativo decidir.
Navegação melhorada
Os dois principais modos de navegação – menu (à esquerda) e tabela de conteúdo (à direita) – foram redesenhados para uma melhor navegação e digitalização. Um novo controlo de paginação (na parte inferior) ajuda-o a saber qual guia é a seguir e qual vem antes.
Blocos de código melhorados
Com o PrismJS, o realce e a personalização da sintaxe são simples.
Pesquisa melhorada
A pesquisa da Algolia foi atualizada para a versão v3, o que nos dá muito mais controlo sobre o conteúdo indexado para resultados. Isto também funciona em dispositivos móveis.
Mas espere, há mais
O repositório de documentos beta do React tem muito a acontecer, e conseguimos aproveitar o poder do código aberto aqui. Há algumas coisas que obtemos quase fora da caixa, como tabela de conteúdos, paginação de documentos, breadcrumbs, SEO, etc. Alguns destes nós ajustámos-nos para melhor servir o nosso contexto, e outros que ainda estamos a explorar.
Contribuir
Para nós, esta é a nova documentação é um passo na direção certa e no início de um novo começo. Queremos que se junte a nós nesta jornada à medida que continuamos a ajudá-lo a tornar os seus websites mais rápidos e seguros sem comprometer a experiência dos programadores. O código-fonte para os documentos do desenvolvedor Layer0 está em um repositório aberto no GitHub e recebemos feedback e pedidos de pull. Se você encontrou um erro de digitação ou uma maneira melhor de explicar algo, por favor, envie um pull request ou envie um problema! Além disso, veja as nossas diretrizes de contribuição.