Crie um site estático usando o VitePress para criar uma bela documentação de ajuda

Introdução

Sempre fui fã dos geradores de sites estáticos como forma de criar um site em HTML a partir de texto (geralmente em Markdown) com suporte a temas criados pela comunidade. Isso permite que você dedique mais tempo à criação de conteúdo do que ao gerenciamento da infraestrutura de um sistema de gerenciamento de conteúdo (CMS) como o WordPress, que exige um banco de dados e uma interface de usuário (UI) para inserir conteúdo. Se eu pudesse resumir as três razões pelas quais gosto de geradores de sites estáticos, seriam:

• Desempenho (as páginas são pré-renderizadas)

• A possibilidade de usar temas

• Eles não exigem que o código seja executado no lado do servidor

Vamos dar uma olhada em um livro bem conhecido chamado VitePress.

vitepressmain.png

Um guia básico sobre o VitePress

O VitePress é o irmão mais novo do VuePress irmão mais novo, e é desenvolvido com base no Vite e Vue.js. Para quem não sabe, o Vite é uma ferramenta de compilação que visa proporcionar uma experiência de desenvolvimento mais rápida e enxuta para projetos web modernos; por isso, pode fazer sentido combiná-lo com um gerador de sites estáticos como o VitePress. O Vue.js é um framework JavaScript progressivo para a criação de interfaces de usuário na web. Um dos problemas iniciais do VuePress era que ele era um aplicativo baseado no Webpack, e demorava muito tempo para iniciar um servidor de desenvolvimento apenas para um documento simples. O VitePress resolve esses problemas com uma inicialização quase instantânea do servidor, uma compilação sob demanda que compila apenas a página que está sendo servida e um HMR extremamente rápido. Vamos começar!

Do zero a um site estático funcional

Primeiro, crie uma pasta onde você desenvolverá seu site estático.

Em seguida, inicialize-o com Yarn ou NPM. Neste exemplo, usaremos o Yarn. Se você não tiver o Yarn instalado, pode baixá-lo na página de downloads. Para quem usa o NPM, a documentação do VitePress está disponível aqui.

Serão feitas uma série de perguntas, e você pode preencher os detalhes aqui ou deixar em branco, como eu fiz.

yarn init
yarn init v1.22.19
question name (static-starter):
question version (1.0.0):
question description:
question entry point (index.js):
question repository url:
question author:
question license (MIT):
question private:
success Saved package.json
Done in 26.93s.

Observação: você sempre pode preencher esses campos mais tarde, ao configurar o site.

Neste momento, você terá apenas um único package.json arquivo. Agora você deve adicionar o VitePress e o Vue como dependências de desenvolvimento para o projeto.

yarn add --dev vitepress vue

Agora precisamos de um local para armazenar os documentos que vamos criar e adicionar um documento de exemplo.

mkdir docs 
cd docs
touch index.md

Edite o conteúdo de index.md para incluir o seguinte texto:

# Hello VitePress.

Agora você deve ter os seguintes arquivos e pastas:

docs 
├── index.md
node_modules 
package.json 
yarn.lock

Precisamos adicionar a seguinte scripts seção à nossa package.json.

{
  "name": "static-starter",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "devDependencies": {
    "vitepress": "^1.0.0-alpha.21",
    "vue": "^3.2.41"
  },
    "scripts": {
      "docs:dev": "vitepress dev docs",
      "docs:build": "vitepress build docs",
      "docs:serve": "vitepress serve docs"
  }
}

Isso nos permitirá ter perfis diferentes, dependendo da situação.

Você pode implantar o servidor executando yarn docs:dev conforme mostrado abaixo.

yarn docs:dev
yarn run v1.22.19
$ vitepress dev docs
vitepress v1.0.0-alpha.21

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

O VitePress oferece suporte à “atualização dinâmica”, o que significa que, depois de salvar um arquivo no projeto, você não precisará recompilar o site para ver as alterações.

Agora você deve ter um servidor em funcionamento, que normalmente fica no seguinte endereço: http://localhost:5173.

helloworld.gif

Parabéns! Nosso aplicativo já está funcionando, e você já pode perceber alguns dos recursos e funcionalidades que conseguimos com o VitePress, tais como:

• Site responsivo com animações

• Desenvolva seguindo a filosofia “Mobile-first”

• Modos escuro e claro integrados

Como adicionar mais páginas e entender a estrutura dos arquivos

Vamos adicionar outra página para a qual o usuário final possa acessar assim que o site carregar. Primeiro, crie um arquivo chamado another-page.md dentro da docs pasta. Adicione o seguinte texto ao conteúdo do arquivo # Another Page.

Agora, sua docs pasta deve estar assim.

docs
├── index.md
├── another-page.md

Você não vai encontrá-la se tentar acessá-la another page.md dentro do seu navegador. Você pode acessar a página manualmente seguindo a URL: http://localhost:5173/another-page.

Observação: Observe que a estrutura de diretórios corresponde ao caminho da URL.

Então, como podemos resolver isso?

Adicionando a navegação

Já temos o básico de um site, mas faltam recursos de navegação para acessar as outras páginas. Normalmente, o menu lateral é usado em sites de documentação. Para adicioná-los, precisamos fazer algumas coisas primeiro.

Para personalizar e adicionar um menu de navegação ao seu site, vamos primeiro criar um .vitepress diretório dentro do seu docs diretório. Depois de concluído, adicione outro arquivo chamado config.js. Essa pasta é onde todos os arquivos de configuração específicos do VitePress serão colocados. A estrutura do seu projeto deve ficar assim:

docs
├── index.md
├── another-page.md
└── .vitepress
    └── config.js

Abra seu vitepress/config.js e adicione o código abaixo:

export default {
  title: 'VitePress',
  description: 'Vonage Loves Developers.'
}

Isso fornecerá um título e uma descrição padrão para o site, que serão indexados pelos mecanismos de busca.

A seguir, vamos configurar nossa barra de navegação de nível superior para incluir dois itens adicionais para o nosso Roteiro e formas para que nossos usuários possam enviar feedback. Adicione o seguinte ao seu vitepress/config.js arquivo, após o description campo.

themeConfig: {
 nav: [
  { text: 'Roadmap', link: '/roadmap' },
  { text: 'Feedback', link: '/feedback' }
]

toplevelnavigation.png

Ótimo! Nosso site está tomando forma! Agora, vamos adicionar nossa barra lateral abaixo do nav elemento que acabamos de criar.

export default {
  title: 'VitePress',
  description: 'Vonage Loves Developers.',
  themeConfig: {
    nav: [
      { text: 'Roadmap', link: '/roadmap' },
      { text: 'Feedback', link: '/feedback' }
    ],
    sidebar: [
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/introduction' },
          { text: 'Getting Started', link: '/getting-started' },
        ]
      }
    ]
  }
}

Agora nosso site está começando a tomar forma! Adicionamos uma barra de navegação principal e uma barra lateral. Também temos uma botão “Próxima página” que leva à página de Introdução (assim que a criarmos).

sidelevelnavigation.png

Vamos então adicionar todas as páginas que acabamos de criar:

Crie os seguintes arquivos chamados roadmap.md, feedback.md, introduction.md e getting-started.md na docs pasta e nomeie-os com o mesmo nome.

Por exemplo, # Roadmap seria inserido dentro do roadmap.md arquivo. Faça isso em todos os arquivos.

Depois que tudo estiver salvo, volte ao seu site para verificar se todos os links agora funcionam como deveriam.

navigationadded.gif

Outras características dignas de destaque

Links de edição do GitHub ou do GitLab

Você pode criar um link automaticamente em cada página para permitir que seus leitores ajudem a contribuir para a precisão do conteúdo por meio de serviços de gerenciamento de Git, como o GitHub ou o GitLab. Para ativar essa função, adicione themeConfig.editLink opções à sua configuração, conforme mostrado abaixo:

export default {
  themeConfig: {
    editLink: {
      pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
      text: 'Edit this page on GitHub'
    }
  }
}

Agora, cada página gerada terá um link para o GitHub (ou GitLab) para que o usuário possa enviar uma solicitação de pull.

editpage.png

Contêineres personalizados

Há suporte integrado para contêineres personalizados quando você quiser destacar algo para o leitor, por exemplo, informações, dicas, caixas de aviso etc.

::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::

Isso é exibido da seguinte forma:

tipbox.png

Destaque de sintaxe em blocos de código

O realce de sintaxe em blocos de código é oferecido de várias maneiras. Veja este exemplo de como você pode destacar uma linha em um bloco de código:

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

syntaxhighlighting.png

Implantando seu aplicativo

Agora que desenvolvemos nosso site estático e adicionamos páginas a ele, além de uma barra de navegação completa, vamos implantar nosso aplicativo. Você pode fazer isso executando o seguinte comando yarn docs:build.

Se tudo funcionar corretamente, você verá o seguinte:

yarn docs:build
yarn run v1.22.19
$ vitepress build docs
vitepress v1.0.0-alpha.21
✓ building client + server bundles...
⠋ rendering pages...(node:3164) ExperimentalWarning: The Fetch API is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
✓ rendering pages...
build complete in 8.29s.
Done in 8.97s.

Os arquivos renderizados serão salvos, por padrão, na página do seu projeto, na pasta dist. Por exemplo, meus arquivos foram renderizados aqui: C:\Users\mbcru\source\static-starter\docs\.vitepress\dist

fileexplorer.png

Conclusão

Agora que seu site estático está funcionando, você pode adicionar recursos específicos de comunicação que a Vonage oferece, como o Videoou Mensagens, etc.!

Se você tiver dúvidas ou sugestões, junte-se a nós no Slack dos desenvolvedores da Vonage ou me envie um tweet no Twitter, e eu entrarei em contato com você. Mais uma vez, obrigado pela leitura, e nos vemos no próximo artigo!