Nel frenetico panorama digitale di oggi, avere un sito di documentazione o un blog ben organizzato e visivamente accattivante è essenziale per catturare l’attenzione del pubblico e tenerlo impegnato. Ma come ottenere questo risultato senza passare infinite ore a occuparsi dello sviluppo web?
Questo articolo spiega come creare e personalizzare un sito di documentazione e blog veloce utilizzando VuePress, un generatore di siti statici (SSG) minimalista ma potente.
Cos’è VuePress?
VuePress è un framework open-source specializzato nella creazione di siti web statici, principalmente orientati alla documentazione e al blogging. È stato creato da Evan You, il genio di Vue.js, e incarna la filosofia di semplicità e facilità d’uso per cui Vue.js è noto.
Perché usare VuePress?
Ecco alcuni validi motivi per cui VuePress potrebbe essere la scelta perfetta per voi.
- Semplicità del Markdown: VuePress semplifica la creazione di contenuti con Markdown, rendendo più facile scrivere e strutturare i contenuti senza formattazioni complesse.
- Integrazione con Vue.js: VuePress integra perfettamente Vue.js, consentendo di creare elementi web interattivi e dinamici per un’esperienza utente coinvolgente.
- Prestazioni e personalizzazione: VuePress offre prestazioni eccellenti con siti web statici a caricamento rapido e ampie opzioni di personalizzazione per adattarsi al vostro stile e alle vostre esigenze.
Come iniziare con VuePress
Prima di immergervi in VuePress, assicuratevi di avere installato Node.js o Yarn Classic sul computer. Ci sono due modi per iniziare con VuePress: utilizzare il generatore create-vuepress-site, che vi aiuterà a creare la struttura di base del sito VuePress, oppure utilizzare l’installazione manuale.
Per questo articolo, utilizzeremo il metodo di installazione manuale.
- Creiamo una nuova directory e modifichiamola:
mkdir vuepress-starter && cd vuepress-starter- Inizializziamo con il nostro gestore di pacchetti preferito. Per questo articolo, usiamo Yarn:
yarn init- Installiamo VuePress nel progetto come developer dependency:
yarn add -D vuepress- Creiamo una cartella docs per contenere tutto il codice e poi creiamo un file README.md, che serve come file di indice del progetto, simile a index.html:
mkdir docs && echo '# Hello VuePress' > docs/README.md- Apriamo il progetto in un editor di codice e aggiungiamo i seguenti script al file package.json in modo da poter servire e ed eseguire la build del sito:
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs"
},A questo punto possiamo servire il sito eseguendo il comando yarn dev. VuePress avvierà il server di sviluppo all’indirizzo http://localhost:8080.
Abbiamo creato un sito di documentazione. Noterete che VuePress offre un tema predefinito pulito e minimalista. Tuttavia, è altamente personalizzabile e vi dà la libertà di creare un aspetto unico per il vostro sito web.
Creare pagine di documentazione
VuePress segue una struttura di directory semplice per organizzare la documentazione. All’interno della cartella del progetto, troverete la cartella docs che abbiamo creato, dove potrete creare file Markdown (.md) per le vostre pagine di documentazione.
Ad esempio, potete creare file come getting-started.md, usage.md e troubleshooting.md. Questi file diventano automaticamente dei percorsi a cui potrete accedere navigando su http://localhost:8080/getting-started, http://localhost:8080/usage e http://localhost:8080/troubleshooting.
Per migliorare l’organizzazione della documentazione, si possono creare delle cartelle dedicate alle pagine di documentazione correlate. Ad esempio, potreste creare una cartella chiamata guide e organizzarla con guide specifiche come using-kinsta-stsh.md. Se utilizzate questa struttura, il contenuto di using-kinsta-stsh.md diventa accessibile tramite un URL come http://localhost:8080/guide/using-kinsta-stsh.
Potete anche creare un file README.md o index.md nella cartella principale guide. Questo file fungerà da pagina di indice, consentendo agli utenti di navigare verso http://localhost:8080/guide/ e di accedere comodamente ai contenuti con una barra laterale che impareremo a configurare nella prossima sezione.
In questo repository di esempio di VuePress, noterete che tutti questi file sono stati creati e che alcuni contenuti markdown sono stati aggiunti a ciascun file. Sentitevi liberi di creare i file in base alle vostre preferenze, sia partendo da zero per soddisfare le vostre esigenze specifiche sia ispirandovi ai contenuti disponibili nel repository.
Personalizzare l’aspetto di VuePress
Una volta creato il sito di documentazione con i contenuti, potreste trovare difficile la navigazione, soprattutto se avete molti file da gestire. Tuttavia, VuePress permette di personalizzare la struttura di navigazione del sito per renderlo più semplice e organizzato.
Per personalizzare l’aspetto e la navigazione del sito, create una cartella .vuepress nella directory principale del progetto. Questa cartella conterrà i file di configurazione e le risorse relative al vostro sito VuePress.
Configurazione della navigazione
Nella cartella .vuepress, creiamo un file config.js. Potete anche utilizzare altri formati di file come YAML (.yml), TOML (.toml) o TypeScript (.ts) per la vostra configurazione.
Nel file config.js potete definire la struttura di navigazione del sito utilizzando l’oggetto themeConfig. Ecco un esempio di configurazione:
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'],
},
],
},
},
};In questo esempio, stiamo configurando le sezioni title e description del sito, definendo i collegamenti di navigazione e impostando una barra laterale per la sezione /guide/.
L’array nav specifica i link di navigazione nella parte superiore del sito. L’oggetto sidebar definisce la struttura della barra laterale per sezioni specifiche. In questo caso, è configurato per la sezione /guide/.
Potete leggere ulteriori informazioni sulla configurazione della barra laterale nella documentazione di VuePress.
Stilizzazione
VuePress permette di personalizzare l’aspetto del proprio sito attraverso gli stili. Potete sovrascrivere gli stili predefiniti utilizzando alcune variabili definite o definire il vostro stile. Per fare una di queste due cose, create una cartella styles nella cartella .vuepress
Per applicare semplici modifiche allo stile del preset predefinito o per definire alcune variabili da utilizzare in seguito, potete creare un file palette.styl in .vuepress/styles. Queste sono alcune variabili predefinite che potete modificare:
// 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 = 419pxQueste variabili possono essere utilizzate per mantenere uno stile coerente in tutto il sito. VuePress offre anche un modo pratico per aggiungere altri stili. Si può creare un file index.styl nella cartella .vuepress/styles dove utilizzare la normale sintassi CSS:
.content {
font-size 30px
}Per saperne di più sullo stile di VuePress, consultate la documentazione ufficiale.
Usare i componenti
VuePress supporta l’uso di componenti per migliorare la funzionalità e l’aspetto delle vostre pagine. Potete creare componenti Vue e includerli nei vostri file Markdown. Create un componente components in .vuepres e tutti i file *.vue che si trovano in .vuepress/components verranno automaticamente registrati come componenti globali.
Ad esempio, consideriamo la creazione di due componenti, HomeOptions.vue e HostingBanner.vue:
.
└─ .vuepress
└─ components
├─ HomeOptions.vue
└─ HostingBanner.vueAll’interno di questi file di componenti vue.js, possiamo aggiungere codici CSS. Aggiungiamo il codice ai componenti HomeOptions.vue e HostingBanner.vue.
Aggiungiamo il codice sottostante a 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>Inoltre, aggiungiamo il codice sottostante a 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>All’interno di qualsiasi file Markdown, possiamo utilizzare direttamente i componenti (i nomi vengono dedotti dai nomi dei file):
<HomeOptions/>
<HostingBanner/>Per saperne di più sui componenti in VuePress, consultate la documentazione.
Personalizzare la homepage
In VuePress, il tema predefinito offre un layout predefinito della homepage che potete utilizzare per creare un punto di partenza accattivante e informativo per il vostro sito. Per utilizzare questo layout della homepage, dovete specificare home: true e includere alcuni metadati aggiuntivi nel frontmatter YAML del file README.md principale.
Ecco un esempio di 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
---Tutte queste configurazioni fanno sì che l’homepage della documentazione abbia l’aspetto seguente:
Vale la pena notare che è possibile disabilitare i valori heroText e tagline o qualsiasi altro valore impostando i campi corrispondenti a null se preferite un layout più semplice o non includerlo. Qualsiasi contenuto incluso dopo il frontmatter YAML (cioè la sezione dei metadati) sarà trattato come un normale Markdown e sarà reso dopo la sezione delle caratteristiche.
Se desiderate un layout della homepage completamente personalizzato, VuePress supporta anche i layout personalizzati. Inoltre, potete creare un footer ricco di testo utilizzando la sintassi degli slot Markdown, che offre una maggiore flessibilità nella visualizzazione dei contenuti del footer. Ecco un esempio di come impostare un footer ricco di testo:
---
home: true
---
::: slot footer
Made with ❤️ by Kinsta. [Static Site Hosting](https://kinsta.com/static-site-hosting/)
:::In questo caso, il contenuto della sezione ::: slot footer permette di includere link e informazioni aggiuntive nell’area del footer della homepage.
Ora che abbiamo capito come eseguire le personalizzazioni di cui sopra, aggiungiamo i componenti creati in precedenza alla Homepage e rimuoviamo alcune opzioni per migliorare l’aspetto della Homepage:
---
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/)
:::Seguendo queste tecniche di personalizzazione di VuePress, potrete creare un sito di documentazione che non solo fornisca contenuti di valore, ma che offra anche un’esperienza utente eccellente grazie a una navigazione organizzata e a uno stile accattivante.
Potete leggere ulteriori informazioni sulla personalizzazione del tema predefinito nella documentazione.
Creare una sezione blog con VuePress
Aggiungere una sezione blog al vostro sito VuePress è un gioco da ragazzi perché VuePress permette di scrivere componenti Vue personalizzati che possono essere inseriti in qualsiasi file Markdown. Creiamo un componente che restituirà l’elenco dei post del blog.
Creiamo un file BlogIndex.vue nella cartella components e aggiungiamo il seguente codice:
<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>Nel frammento di codice fornito, definiamo un modello Vue che scorre i post del blog utilizzando v-for, mostrando il titolo del post, la descrizione e un link “Leggi di più” per ogni post.
La sezione script esporta un componente Vue che calcola e recupera i post del blog. Questi post vengono filtrati in base al loro percorso (che inizia con /blog/) e all’assenza di un attributo frontmatter blog_index. Vengono poi ordinati per data in ordine decrescente per presentare prima i post più recenti.
Quando creerete nuovi post sul blog, dovrete specificare la data del post come parte delle informazioni di frontmatter. Questo vi aiuterà a ordinare i post in modo da far apparire per primi quelli più recenti.
Per archiviare i post del blog, creiamo una cartella denominata blog nella root del progetto. In questa cartella, aggiungiamo un file README.md. Questo sarà l’indice del blog ed è qui che includeremo il componente BlogIndex per elencare tutti i post del blog.
---
blog_index: true
---
# Blog
Welcome To Our Blog
<BlogIndex />Assicuratevi di aggiungere l’attributo blog_index frontmatter, in quanto è fondamentale per garantire che l’indice del blog stesso non sia elencato tra i singoli post del blog. Questo attributo viene utilizzato per filtrare i post nella proprietà posts computed del componente BlogIndex.vue.
Quindi, creiamo una cartella blog nella root del progetto che memorizzerà tutti i post del blog e creerà ogni post. Ad esempio, creiamo un file first-post.md e aggiungiamo il seguente contenuto 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.Per ogni post del blog, assicuratevi di definire le impostazioni essenziali del frontmatter, come il titolo del post, la data e altri metadati rilevanti. Questa organizzazione meticolosa garantisce che i post del blog siano presentati in modo coerente e che il vostro pubblico abbia un’esperienza di lettura avvincente.
Infine, potete aggiungere la navigazione del blog alla navbar nel file .vuepress/config.js:
nav: [
{
text: 'Guide',
link: '/guide/',
},
{ text: 'Blog', link: '/blog/' },
{
text: 'Static Site Hosting',
link: 'https://kinsta.com/static-site-hosting/',
},
],Potete fare molto di più con VuePress, ad esempio aggiungere dei plugin, utilizzare un tema separato o addirittura creare un tema personale.
Distribuire un sito statico VuePress su Kinsta
Kinsta vi permette di ospitare fino a 100 siti web statici gratuitamente. Potete farlo inviando il codice al vostro provider Git preferito (Bitbucket, GitHub o GitLab) e poi distribuendolo su Kinsta.
Prima di inviare i vostri file a qualsiasi provider Git, create un file .gitignore nella root del progetto per specificare i file e le cartelle che Git deve ignorare quando invia il vostro codice:
# dependencies
/node_modules
# build directory
./docs/.vuepress/dist
/publicPer questa guida utilizzeremo GitHub. Create un repository su GitHub per inviare il codice sorgente. Una volta che il repository sarà pronto, seguite questi passaggi per distribuire il vostro sito statico su Kinsta:
- Accedete o create un account per visualizzare la vostra dashboard MyKinsta.
- Autorizzate Kinsta con il vostro provider Git.
- Cliccate su Siti statici nella barra laterale di sinistra e poi su Aggiungi sito.
- Selezionate il repository e il branch da cui desiderate effettuare il deploy.
- Assegnate un nome unico al vostro sito.
- Aggiungete le impostazioni di build nel seguente formato:
- Comando di build:
npm run build - Versione node:
16.20.0 - Directory di pubblicazione:
./docs/.vuepress/distopublic
- Comando di build:
- Infine, cliccate su Crea sito.
E il gioco è fatto! In pochi secondi avrete un sito distribuito. Viene fornito un link per accedere alla versione distribuita del vostro sito. In seguito potrete aggiungere il vostro dominio personalizzato e il vostro certificato SSL, se lo desiderate.
In alternativa all’Hosting di Siti Statici, potete scegliere di distribuire il vostro sito statico con l’Hosting di Applicazioni di Kinsta, che offre una maggiore flessibilità di hosting, una gamma più ampia di vantaggi e l’accesso a funzioni più robuste. Ad esempio, la scalabilità, la distribuzione personalizzata tramite un file Docker e l’analisi completa dei dati storici o in tempo reale.
Riepilogo
VuePress è uno strumento versatile e potente per creare velocemente siti di documentazione e blog. Grazie alla sua semplice configurazione, ai temi e ai plugin personalizzabili, potrete creare una piattaforma informativa e visivamente accattivante per il vostro pubblico.
Iniziate a creare il vostro sito VuePress oggi stesso e condividete le vostre conoscenze con il mondo intero grazie al nostro Hosting di Siti Statici gratuito!
Avete utilizzato VuePress per creare qualcosa? Non esitate a condividere con noi i vostri progetti e le vostre esperienze nella sezione commenti qui sotto.
Lascia un commento