Criando sites, landing pages e documentações com docusaurus
Fala galera, neste post iremos falar sobre como criar sites, landing pages e documentações utilizando o docusaurus. Mas antes devemos saber o que é o docusaurus ? Docusaurus é um projeto open source, mantido pelo facebook e desenvolvido utilizando Javascript mais especificamente reactjs.
Seu conteúdo é gerenciado de forma estática e após a publicação são gerados os arquivos em html, css, js, img e etc.
Para utilizar o docusaurus é necessário instalar um pacote via npm ou yarn. Irei utilizar o gerenciado de dependências npm , para instalar o docusaurus de forma global execute o seguinte comando:
OBS: A versão do docusaurus utilizada neste exemplo é a 1.14.4.
Após a instalação de forma global, iremos utilizar o docusaurus-init para a criação do boleiplait do projeto, para isso crie uma pasta, entre nessa pasta e posteriormente execute o comando: docusaurus-init,(isso é feito porque os arquivos do projeto vem “soltos” no diretório de instalação do projeto) conforme exemplo abaixo:
Os comandos acima realizam as seguintes acões:
- mkdir criando-site-lp-docs-docusaurus : cria a pasta do projeto;
- cd criando-site-lp-docs-docusaurus: entra na pasta criada;
- docusaurus-init : cria de fato um projeto docusaurus;
- cd criando-site-lp-docs-docusaurus/website : entra na pasta do projeto que tem o arquivo package.json
- npm start : “starta” o servidor por padrão na porta 3000.
Caso tenha dado tudo certo ao realizar o comando npm start o resultado deve ser similar a imagem abaixo:
Inicialmente um projeto docusaurus possui a seguinte estrutura:
- website: Contém os arquivos relacionados ao site e blog, arquivo e pasta de dependências, arquivo de configuração, tradução entre outros;
- docs: Pasta que contém os arquivos em formato markdown, são utilizados de fato na parte relacionada ao website de documentação
- .dockerignore : Arquivo com finalidade similar ao .gitignore, onde a diferença são os arquivos que devem ser ignorados pelo docker;
- .gitignore: Arquivo que contém a lista de arquivos e pastas que devem ser ignorados pelo controle de versão.
- docker-compose.yml: Arquivo que contém o mapeamento dos serviços, portas, volumes e pasta de trabalho do docker
- Dockerfile: Arquivo que contém os passos necessários para build de um container docker, utiliza a imagem oficial do node na versão lts no docker hub.
Configurações iniciais
O arquivo de configuração fica em: website/siteConfig.js, este arquivo possui as seguintes de configuração users e siteConfig. Para alterar o nome do site altere o atributo title da constante siteConfig e o subtitulo é representado pelo atributo tagline, irei alterar o nome do mesmo para “Post sobre docusaurus” e o subtitulo “Um site sobre o docusaurus” para conforme abaixo:
Note que ao salvar as informações provavelmente serão alteradas. OBS: o caso de alteração nas páginas do site(markdown) o livereload é automático, entretanto no caso de configurações no site é recomendado startar o servidor caso o livereload não aconteça.
Agora para fechar as apresentação sobre configurações iniciais, irei apresentar como realizar a alteração das cores primárias e secundárias, alteração do favicon e icones da header, footer e texto sobre copyright.
Para alterar as cores primárias e secundárias do site, vá no objeto colors presente na constante siteConfig no arquivo website/siteConfig.js:
Veja que ao alterar as configurações de cores, a mesma refletida nas cores do: menu, fonte, hover entre outros:
Agora iremos alterar o favicon e icones presentes na footer, para isso irei realizar da logo do docusaurus em formato .svg presente neste link e iremos salvar dentro da pasta website/static/img com o nome docusaurus.svg.
Após salvar o arquivo, irei alterar os seguinte atributos: headerIcon, footerIcon e favicon presente na constante siteConfig no arquivo website/siteConfig.js, para alterar o favico irei fazer o download do favico do docusaurus na mesma pasta, utilizando essa url e em seguida irei alterar o atributo favicon:
OBS: Todos os arquivos de css e img por default, ficam na pasta website/static.
Para fechar o que foi proposto sobre configurações iniciais, iremos alterar a configuração a respeito de copyright, para isso altere o atributo copyright presente na constante siteConfig no arquivo website/siteConfig.js:
Configuração de menu e páginas iniciais e de documentações
Por padrão o docusaurus vem com 3 páginas help.js, index.js e users.js, que fica localizada em website/pages/en. Essas páginas são componentes implementados em reactjs utilizando o padrão CommonJS.
No caso dos arquivos index.js e users.js utilizam a estratégia de componentes de classe, ja no caso do arquivo help.js é utilizada a estratégia de componente funcional. Outro ponto importante é que no caso do componente de classe que presenta a página index ele possui duas classes no mesmo arquivo são elas HomeSplash e Index.
Para exemplificar melhor iremos alterar os nomes dos 3 botões que aparecem na home.
Vá até o arquivo website/pages/en/index.js e edite os botões presente no return da classe HomeSplash, neste caso irei realizar as seguintes alterações:
- De: Try It Out Para: Sobre
- De: Example Link Para: Como instalar ?
- De: Example Link 2 Para: Como configurar ?
Note que no caso os botões Example Link e Example Link 2 os mesmos direcionam para páginas de documentações que apesar de serem escritas em markdown (.md) devem ser referenciadas como HTML (.html), pois ao final do bundle os mesmos serão gerados em html. Já no caso do botão Try It Out é uma ancora que utiliza um componente chamado Block (na classe Index presente no mesmo arquivo) com o id=”try”.
Também irei editar o texto e alterar o icone para isso que esta dentro da const TryOut seu conteúdo esta sendo utilizado pelo botão Try presente na classe Index. Para isso utilizei um SVG presente no site da documentação do docusaurus que pode ser visto nesta url, baixe o mesmo para a pasta website/static/img e alterei o nome do arquivo para build_with_react.svg
OBS: Para facilitar a localização, copiei o componente com as alterações feitas e deixei disponível acima.
Após realizar as alterações e clicar no botão sobre, você terá o seguinte resultado:
Antes de falar sobre a alteração do menu propriamente dita, temos duas configurações referentes a menu, a primeira esta relacionada ao menu superior e esta presente no seguinte arquivo website/siteConfig.js presente no array de objetos chamados headerLinks. Já a outra configuração esta relacionada ao menu das páginas de documentações presente no arquivo website/sidebars.json.
Vamos alterar o item de menu superior chamado Docs iremos alterar o nome para Documentação e também iremos alterar a opção chamada help para Ajuda, para isso vá até o arquivo website/siteConfig.js e altere o atributo label presente no array de objetos headerLinks.
Após realizar as alterações você terá o seguinte resultado:
Agora iremos alterar as opções de menu presente nos Docs para isso clique no botão Documentação, veja que neste parte em específico, temos uma sidebar no canto esquerdo, para alterar essas opções, vá no arquivo website/sidebars.json, veja que este arquivo contém uma serie de objetos e para cada atributo desse objeto, recebe um array com os ids das páginas de documentação, por sua vez essa página (arquivo em formato .md presente na pasta docs) possui um atributo chamado sidebar_label para alterar o nome apresentado na opção de menu, deverá ser alterado esse atributo.
Para entendermos melhor a explicação acima, digamos que iremos alterar o nome do primeiro item de “Example Page” para “Como instalar ?”, para isso temos que ir no arquivo website/sidebars.json e localizar o id do documento que esta dentro da pasta docs. Ao consultar o arquivo website/sidebars.json vimos que o id do documento é o doc1, agora indo até o arquivo docs/doc1.md e altere o nome do atributo sidebar_label:
Realizando a alteração proposta acima, você terá o seguinte resultado:
Configuração de redes sociais no docussaurus
No arquivo website/siteConfig.js é possível habilitar os comentários com o facebook, botão de seguir no twitter em outros apenas informando nome de usuário ou id referente a APP de Facebook e etc, conforme diretivas apresentadas abaixo, devem ser adicionadas:
Neste caso apenas adicionei as configurações referente ao twitter, após fazer isso, veja que passou a ser apresentado na footer um botão referente ao twitter:
Blog e Documentação
Os arquivos referentes aos posts do blog ficam na pasta website/blog. Os mesmos são escritos utilizando a linguagem de marcação markdown. Os nomes dos arquivos são organizados por data e nome exemplo: 2020-02-29-iniciando-com-docusaurus.md.
Para apresentar o botão de leia mais no post, basta utilizar o comentário
<!--truncate-->
logo abaixo do texto que será apresentado.
Outra funcionalidade interessante é que no post que é escrito em markdown, é possível referenciar o autor de 3 formas:
- Nome por meio do atributo: author
- Url externa como site ou Twitter por exemplo por meio do atributo: authorURL
- ID do Facebook por meio do atributo: 100002918863369
Ao preencher essas informações a mesma foto que é apresentada no perfil do facebook, será apresentado no blog. Iremos criar uma postagem no blog, para isso vamos criar um arquivo na pasta website/blog com o seguinte nome e extensão: 2020-02-29-iniciando-com-docusaurus.md e como conteúdo do post irei colocar a seguinte marcação:
Após isso, acesse a opção blog presente no menu superior e em seguida veja o resultado:
Agora para fechar iremos escrever uma página de DOC (documentação), o processo é parecido com a escrita de um post, entretanto as páginas de documentação ficam no diretório docs e as páginas de documentação possuem um id que é utilizado para referenciar a mesma no arquivo de menu website/sidebars.json.
Outra caracteristica importante além do id, uma página de documentação, também possui um atributo chamado sidebar_label que é responsável por receber o nome da página conforme será apresentado no menu lateral.
Iremos criar uma página de documentação, para isso vamos criar um arquivo na pasta docs chamado minhadocumentacao.md, com o seguinte conteúdo:
Com isso neste post foi apresentado, algumas possibilidades do que é possível fazer utilizando o docusaurus. Na data na qual estou escrevendo este post a versão estável do docusaurus é a 1.14.4, entretanto a versão 2 esta sendo desenvolvida e se encontra na versão alpha 43, para consultar a respeito da 2 vesão acesse este link