No cenário digital acelerado de hoje, ter uma documentação ou site de blog bem organizado e visualmente atraente é essencial para captar a atenção do seu público e mantê-los engajados. Mas como você pode conseguir isso sem gastar horas intermináveis em desenvolvimento web?
Este artigo explica como você pode criar e personalizar um site rápido de documentação e blog usando o VuePress, um gerador de site estático (SSG) minimalista, porém poderoso.
O que é VuePress?
O VuePress é uma framework de código aberto especializado na geração de sites estáticos, voltados principalmente para documentação e blogs. Ele foi criado por Evan You, o gênio por trás do Vue.js, e incorpora a filosofia de simplicidade e facilidade de uso pela qual o Vue.js é conhecido.
Por que usar o VuePress?
Aqui estão alguns motivos convincentes pelos quais o VuePress pode ser a escolha perfeita para você.
- Simplicidade do markdown: O VuePress simplifica a criação de conteúdo com Markdown, facilitando a escrita e a estruturação de conteúdo sem formatação complexa.
- Integração com o Vue.js: O VuePress integra perfeitamente o Vue.js, permitindo elementos interativos e dinâmicos da web para uma experiência de usuário envolvente.
- Desempenho e personalização: O VuePress oferece excelente desempenho com sites estáticos de carregamento rápido e amplas opções de personalização para atender ao seu estilo e às suas necessidades.
Começando com o VuePress
Antes de iniciar com o VuePress, certifique-se de que você tenha o Node.js ou o Yarn Classic instalados no seu computador. Existem duas maneiras de começar com o VuePress: você pode usar o gerador create-vuepress-site, que ajudará a criar a estrutura básica do site VuePress para você, ou usar a instalação manual.
Para este artigo, vamos usar o método de instalação manual.
- Crie um novo diretório e altere ele:
mkdir vuepress-starter && cd vuepress-starter- Inicialize com o gerenciador de pacotes de sua preferência. Para este artigo, vamos usar o Yarn:
yarn init- Instale o VuePress em seu projeto como uma dependência de desenvolvedor:
yarn add -D vuepress- Crie uma pasta docs para armazenar todo o seu código e, em seguida, crie um arquivo README.md, que serve como o arquivo de índice do seu projeto, semelhante ao index.html:
mkdir docs && echo '# Hello VuePress' > docs/README.md- Abra seu projeto em um editor de código e adicione os seguintes scripts ao arquivo package.json para que você possa servir e criar seu site:
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs"
},Agora você pode servir seu site executando o comando yarn dev. O VuePress iniciará seu servidor de desenvolvimento em http://localhost:8080.
Agora você criou um site de documentação. Você perceberá que o VuePress oferece um tema padrão limpo e minimalista pronto para uso. No entanto, ele é altamente personalizável, dando a você a liberdade criativa para criar uma aparência exclusiva para o seu site.
Criando páginas de documentação
O VuePress segue uma estrutura de diretórios simples para organizar a documentação. Dentro da pasta do seu projeto, você encontrará o diretório docs que criamos, onde poderá criar arquivos Markdown (.md) para suas páginas de documentação.
Por exemplo, você pode criar arquivos como getting-started.md, usage.md e troubleshooting.md. Esses arquivos tornam-se automaticamente rotas que podem ser acessadas quando você navega para http://localhost:8080/getting-started, http://localhost:8080/usage e http://localhost:8080/troubleshooting.
Para aprimorar a organização da sua documentação, você pode criar pastas dedicadas para páginas de documentação relacionadas. Por exemplo, você pode criar uma pasta chamada guide e organizá-la com guias específicos, como using-kinsta-stsh.md. Quando você emprega essa estrutura, o conteúdo em using-kinsta-stsh.md torna-se acessível por meio de um URL como http://localhost:8080/guide/using-kinsta-stsh.
Você também pode criar um arquivo README.md ou index.md no nível raiz da pasta guide. Esse arquivo servirá como página de índice, permitindo que os usuários naveguem para http://localhost:8080/guide/ e acessem convenientemente o conteúdo com uma barra lateral que você aprenderá a configurar na próxima seção.
Neste repositório de amostra do VuePress, você notará que todos esses arquivos foram criados e que algum conteúdo markdown foi adicionado a cada arquivo. Sinta-se à vontade para criar seus arquivos de acordo com suas preferências, seja do zero para atender às suas necessidades específicas ou inspirando-se no conteúdo disponível no repositório.
Personalizando a aparência do VuePress
Depois de criar seu site de documentação com conteúdo, você pode achar difícil navegar nele, especialmente se tiver muitos arquivos para gerenciar. No entanto, o VuePress permite que você personalize a estrutura de navegação do seu site para torná-lo mais fácil de usar e organizado.
Para personalizar a aparência e a navegação do seu site, crie uma pasta .vuepress no diretório raiz do seu projeto. Essa pasta conterá arquivos de configuração e ativos relacionados ao seu site VuePress.
Configuração de navegação
Na pasta .vuepress, crie um arquivo config.js. Você também pode usar outros formatos de arquivo como YAML (.yml), TOML (.toml) ou TypeScript (.ts) para sua configuração.
No seu arquivo config.js, você pode definir a estrutura de navegação do seu site usando o objeto themeConfig. Aqui está um exemplo de configuração:
module.exports = {
title: 'Kinsta Vuepress',
description: 'A VuePress QuickStart for Kinsta',
themeConfig: {
nav: [
{
text: 'Guide',
link: '/guide/',
},
{
text: 'Static Site Hosting',
link: 'https://kinsta.com/static-site-hosting/',
},
],
sidebar: {
'/guide/': [
{
title: 'Guide',
collapsable: false,
children: ['', 'using-kinsta-stsh'],
},
],
},
},
};Neste exemplo, estamos configurando as seções title e description do site, definindo links de navegação e configurando uma barra lateral para a seção /guide/.
A array nav especifica os links de navegação na parte superior do site. O objeto sidebar define a estrutura da barra lateral para seções específicas. Nesse caso, ele está configurado para a seção /guide/.
Você pode ler mais sobre a configuração da barra de navegação na documentação do VuePress.
Estilo
O VuePress permite que você personalize a aparência do seu site por meio de estilos. Você pode substituir os estilos padrão usando algumas variáveis definidas ou definir seu próprio estilo. Para fazer isso, você deve criar uma pasta de estilos na pasta .vuepress
Para aplicar substituições simples ao estilo da predefinição padrão ou definir algumas variáveis a serem usadas posteriormente, você pode criar um arquivo palette.styl em .vuepress/styles. Estas são algumas variáveis predefinidas que você pode ajustar:
// colors
$accentColor = #5333ED
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
$arrowBgColor = #ccc
$badgeTipColor = #42b983
$badgeWarningColor = darken(#ffe564, 35%)
$badgeErrorColor = #DA5961
// layout
$navbarHeight = 3.6rem
$sidebarWidth = 20rem
$contentWidth = 740px
$homePageWidth = 960px
// responsive breakpoints
$MQNarrow = 959px
$MQMobile = 719px
$MQMobileNarrow = 419pxEssas variáveis podem ser usadas para manter um estilo consistente em todo o seu site. O VuePress também oferece uma maneira conveniente de você adicionar estilos extras. Você pode criar um arquivo index.styl na pasta .vuepress/styles, onde pode usar a sintaxe CSS normal:
.content {
font-size 30px
}Leia mais sobre como estilizar o VuePress na documentação oficial.
Uso de componentes
O VuePress suporta o uso de componentes para aprimorar a funcionalidade e a aparência de suas páginas. Você pode criar componentes Vue e incluí-los em seus arquivos Markdown. Criar um componente em .vuepres e, em seguida, todos os arquivos *.vue encontrados em .vuepress/components são automaticamente registrados como componentes globais.
Por exemplo, considere a criação de dois componentes, HomeOptions.vue e HostingBanner.vue:
.
└─ .vuepress
└─ components
├─ HomeOptions.vue
└─ HostingBanner.vueDentro desses arquivos de componentes vue.js, você pode adicionar códigos CSS. Vamos adicionar código aos componentes HomeOptions.vue e HostingBanner.vue.
Adicione o código abaixo ao HomeOptions.vue:
<template>
<div class="options">
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/static-site-quick-start-examples/"
target="_blank"
>
<h3>Quick Start Examples</h3>
</a>
<p>Explore quick start examples for setting up static sites.</p>
</div>
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/getting-started-static-site-hosting/"
target="_blank"
>
<h3>Getting Started</h3>
</a>
<p>Learn how to get started with static site hosting.</p>
</div>
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/manage-static-sites/"
target="_blank"
>
<h3>Manage Static Sites</h3>
</a>
<p>Discover how to efficiently manage your static sites.</p>
</div>
</div>
</template>
<style scoped>
a {
color: #2c3e50;
}
a:hover {
color: #5333ed;
}
.options {
display: flex;
gap: 10px;
margin: 40px 0;
}
.option {
border: 2px solid #eaecef;
border-radius: 5px;
padding: 10px;
}
</style>Além disso, adicione o código abaixo ao HostingBanner.vue:
<template>
<div class="banner">
<p>Host Your Static Site With Kinsta for Free!</p>
<a
href="https://kinsta.com/docs/static-site-hosting/"
target="_blank"
class="btn"
>Read More</a
>
</div>
</template>
<style> scoped>
.banner {
background: rgb(156, 85, 34);
background: linear-gradient(
90deg,
rgba(156, 85, 34, 1) 0%,
rgba(32, 50, 103, 1) 42%,
rgba(13, 18, 25, 1) 69%,
rgba(22, 47, 60, 1) 100%
);
color: #fff;
padding: 20px;
border-radius: 5px;
display: flex;
justify-content: center;
align-items: center;
flex-direction: column;
}
.banner p {
width: 600px;
font-size: 40px;
font-weight: bold;
text-align: center;
line-height: 50px;
}
.banner .btn {
border-radius: 5px;
padding: 15px;
color: #1f1f1f;
font-weight: bold;
background: #fff;
display: inline-block;
margin-bottom: 10px;
}
.banner .btn:hover {
background: #111319;
color: #fff;
}
</style>Dentro de qualquer arquivo Markdown, você pode usar diretamente os componentes (os nomes são inferidos a partir dos nomes dos arquivos):
<HomeOptions/>
<HostingBanner/>Leia mais sobre componentes no VuePress na documentação.
Personalizando a página inicial
No VuePress, o tema padrão oferece um layout de página inicial predefinido que você pode usar para criar um ponto de partida envolvente e informativo para o seu site. Para usar esse layout de página inicial, você precisa especificar home: true e incluir alguns metadados adicionais no frontmatter YAML do seu arquivo raiz README.md.
Aqui está um exemplo do frontmatter YAML:
---
home: true
heroImage: /hero.png
heroText: Hero Title
tagline: Hero subtitle
actionText: Get Started →
actionLink: /guide/
features:
- title: Simplicity First
details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2018-present Evan You
---Todas essas configurações fazem com que a página inicial da sua documentação tenha a seguinte aparência:
Vale a pena observar que você pode desativar heroText e tagline ou qualquer outro valor definindo seus campos correspondentes como null se preferir um layout mais simples ou não incluí-lo. Qualquer conteúdo que você incluir após o frontmatter YAML (ou seja, a seção de metadados) será tratado como Markdown regular e será renderizado após a seção de recursos.
Se você quiser um layout de página inicial totalmente personalizado, o VuePress também oferece suporte a Layouts personalizados. Além disso, você pode criar um rodapé com rich text usando a sintaxe de slot Markdown, oferecendo mais flexibilidade na exibição do conteúdo do rodapé. Aqui está um exemplo de como você pode definir um rodapé com rich-text:
---
home: true
---
::: slot footer
Made with ❤️ by Kinsta. [Static Site Hosting](https://kinsta.com/static-site-hosting/)
:::Nesse caso, o conteúdo da seção ::: slot footer permite que você inclua links e informações adicionais na área do rodapé da sua página inicial.
Agora que você sabe como realizar as personalizações acima, adicione os componentes criados anteriormente à página inicial e remova algumas opções para que a página inicial tenha uma aparência melhor:
---
home: true
tagline: A VuePress QuickStart for Kinsta
actionText: Quick Start →
actionLink: /guide/
---
<HomeOptions/>
<HostingBanner/>
::: slot footer
Made with ❤️ by Kinsta. [Static Site Hosting](https://kinsta.com/static-site-hosting/)
:::
Seguindo essas técnicas de personalização do VuePress, você pode criar um site de documentação que não apenas forneça conteúdo valioso, mas também ofereça uma excelente experiência ao usuário com navegação organizada e estilo atraente.
Você pode ler mais sobre a personalização do tema padrão na documentação.
Criando uma seção de blog com o VuePress
Adicionar uma seção de blog ao seu site VuePress é muito fácil, pois o VuePress permite que você escreva componentes Vue personalizados que podem ser inseridos em qualquer arquivo Markdown. Vamos criar um componente que renderizará a lista de publicações do blog.
Crie um arquivo BlogIndex.vue na pasta de components e adicione o seguinte código:
<template>
<div>
<div v-for="post in posts" v-bind:key="post.path">
<h2>
<router-link> :to="post.path">{{ post.frontmatter.title }}</router-link>
</h2>
<p>{{ post.frontmatter.description }}</p>
<p><router-link> :to="post.path">Read more</router-link></p>
</div>
</div>
</template>
<script>>
export default {
computed: {
posts() {
return this.$site.pages
.filter(
(x) => x.path.startsWith('/blog/') && !x.frontmatter.blog_index
)
.sort(
(a, b) =>
new Date(b.frontmatter.date) - new Date(a.frontmatter.date)
);
},
},
};
</script>No trecho de código fornecido, você define um template Vue que percorre as publicações do seu blog usando v-for, exibindo o título do artigo, a descrição e um link “Leia mais” para cada publicação.
A seção de script exporta um componente Vue que calcula e recupera as publicações do blog. Essas publicações são filtradas com base em seu caminho (começando com /blog/) e na ausência de um atributo de frontmatter blog_index. Em seguida, elas são classificadas por data em ordem decrescente para apresentar primeiro as publicações mais recentes.
Ao criar novos artigos de blog, você precisará especificar a data da publicação como parte das informações do frontmatter. Isso ajudará a classificar os artigos de modo que as mais recentes apareçam primeiro.
Para armazenar os artigos do blog, crie uma pasta chamada blog na raiz do projeto. Nessa pasta, adicione um arquivo README.md. Esse será o índice do blog e é onde você incluirá o componente BlogIndex para listar todos os artigos do blog.
---
blog_index: true
---
# Blog
Welcome To Our Blog
<BlogIndex />Certifique-se de adicionar o atributo blog_index frontmatter, pois ele é fundamental para garantir que o próprio índice do blog não seja listado entre os artigos individuais do blog. Esse atributo é utilizado quando você filtra os artigos na propriedade posts computed do componente BlogIndex.vue.
Em seguida, crie uma pasta de blog na raiz do projeto que armazenará todos os artigos do blog e criará cada artigo. Por exemplo, crie um arquivo first-post.md e adicione o seguinte conteúdo markdown:
---
title: "My Exciting VuePress Blog Journey"
date: 2023-09-28
description: "Exploring VuePress, a versatile static site generator, and sharing my experiences along the way."
---
# My Exciting VuePress Blog Journey
In this inaugural blog post, I embark on an exciting journey with VuePress, a powerful static site generator that's perfect for creating documentation, blogs, and more. As I delve into the world of VuePress, I'll be sharing my experiences, insights, and tips on making the most out of this fantastic tool.Para cada artigo de blog, certifique-se de que você definiu as configurações essenciais do frontmatter, como o título do artigo, a data e outros metadados relevantes. Essa organização meticulosa garante que as publicações do blog sejam apresentadas de forma coesa e proporciona uma experiência de leitura atraente para o seu público.
Por fim, você pode adicionar a navegação do blog à sua barra de navegação no arquivo .vuepress/config.js:
nav: [
{
text: 'Guide',
link: '/guide/',
},
{ text: 'Blog', link: '/blog/' },
{
text: 'Static Site Hosting',
link: 'https://kinsta.com/static-site-hosting/',
},
],Há muito mais que você pode fazer com o VuePress, como adicionar plugins, usar um tema separado ou até mesmo criar seu próprio tema.
Implante o site estático do VuePress na Kinsta
A Kinsta permite que você hospede até 100 sites estáticos gratuitamente. Você pode fazer isso enviando seu código para o provedor Git de sua preferência (Bitbucket, GitHub ou GitLab) e depois implantar na Kinsta.
Antes de enviar seus arquivos para qualquer provedor Git, crie um arquivo .gitignore na raiz do seu projeto para especificar os arquivos e pastas que o Git deve ignorar ao enviar seu código:
# dependencies
/node_modules
# build directory
./docs/.vuepress/dist
/publicPara este guia, usamos o GitHub. Crie um repositório no GitHub para enviar seu código-fonte. Quando seu repositório estiver pronto, siga estas etapas para implantar seu site estático na Kinsta:
- Faça login ou crie uma conta para visualizar seu painel MyKinsta.
- Autorize a Kinsta com seu provedor Git.
- Clique em Sites estáticos na barra lateral esquerda e, em seguida, clique em Adicionar site.
- Selecione o repositório e a branch a partir da qual você deseja implantar.
- Atribua um nome exclusivo ao seu site.
- Adicione as configurações de build no seguinte formato:
- Comando de build:
npm run build - Versão do node:
16.20.0 - Diretório de publicação:
./docs/.vuepress/distoupublic
- Comando de build:
- Por fim, clique em Criar site.
E é isso! Agora você tem um site implantado em poucos segundos. Você receberá um link para acessar a versão implantada do seu site. Posteriormente, você poderá adicionar seu domínio personalizado e o certificado SSL, se desejar.
Como alternativa à Hospedagem de Site Estático, você pode optar por implantar seu site estático com a Hospedagem de Aplicativos da Kinsta, que oferece maior flexibilidade de hospedagem, uma gama mais ampla de benefícios e acesso a recursos mais robustos. Por exemplo, escalabilidade, implantação personalizada usando um Dockerfile e análises abrangentes que englobam dados históricos em tempo real.
Resumo
O VuePress é uma ferramenta versátil e avançada para a criação rápida de sites de documentação e blogs. Com sua configuração simples, temas personalizáveis e plugins, você pode criar uma plataforma informativa e visualmente atraente para o seu público.
Comece a criar seu site VuePress hoje mesmo e compartilhe seu conhecimento com o mundo hospedando gratuitamente em nossa Hospedagem de Site Estático!
Você já utilizou o VuePress para criar alguma coisa? Sinta-se à vontade para compartilhar seus projetos e experiências conosco na seção de comentários abaixo.
Deixe um comentário