{"id":73735,"date":"2023-10-11T15:22:03","date_gmt":"2023-10-11T14:22:03","guid":{"rendered":"https:\/\/kinsta.com\/it\/?p=73735&preview=true&preview_id=73735"},"modified":"2023-10-13T14:08:57","modified_gmt":"2023-10-13T13:08:57","slug":"vuepress","status":"publish","type":"post","link":"https:\/\/kinsta.com\/it\/blog\/vuepress\/","title":{"rendered":"Creare e personalizzare un sito blog e di documentazione veloce con VuePress"},"content":{"rendered":"

Nel frenetico panorama digitale di oggi, avere un sito di documentazione o un blog ben organizzato e visivamente accattivante \u00e8 essenziale per catturare l’attenzione del pubblico e tenerlo impegnato. Ma come ottenere questo risultato senza passare infinite ore a occuparsi dello sviluppo web<\/a>?<\/p>\n

Questo articolo spiega come creare e personalizzare un sito di documentazione e blog veloce utilizzando VuePress, un generatore di siti statici<\/a> (SSG) minimalista ma potente.<\/p>\n

\"Documentazione<\/a>
Demo della documentazione e del blog di VuePress.<\/figcaption><\/figure>\n
<\/div><\/kinsta-auto-toc>\n

Cos’\u00e8 VuePress?<\/h2>\n

VuePress \u00e8 un framework open-source<\/a> specializzato nella creazione di siti web statici, principalmente orientati alla documentazione e al blogging. \u00c8 stato creato da Evan You<\/a>, il genio di Vue.js<\/a>, e incarna la filosofia di semplicit\u00e0 e facilit\u00e0 d’uso per cui Vue.js \u00e8 noto.<\/p>\n

Perch\u00e9 usare VuePress?<\/h3>\n

Ecco alcuni validi motivi per cui VuePress potrebbe essere la scelta perfetta per voi.<\/p>\n

    \n
  1. Semplicit\u00e0 del Markdown:<\/strong> VuePress semplifica la creazione di contenuti con Markdown, rendendo pi\u00f9 facile scrivere e strutturare i contenuti senza formattazioni complesse.<\/li>\n
  2. Integrazione con Vue.js:<\/strong> VuePress integra perfettamente Vue.js, consentendo di creare elementi web interattivi e dinamici per un’esperienza utente coinvolgente.<\/li>\n
  3. Prestazioni e personalizzazione:<\/strong> 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.<\/li>\n<\/ol>\n

    Come iniziare con VuePress<\/h2>\n

    Prima di immergervi in VuePress, assicuratevi di avere installato Node.js<\/a> o Yarn Classic<\/a> sul computer. Ci sono due modi per iniziare con VuePress: utilizzare il generatore create-vuepress-site<\/a>, che vi aiuter\u00e0 a creare la struttura di base del sito VuePress, oppure utilizzare l’installazione manuale.<\/p>\n

    Per questo articolo, utilizzeremo il metodo di installazione manuale.<\/p>\n

      \n
    1. Creiamo una nuova directory e modifichiamola:<\/li>\n<\/ol>\n
      mkdir vuepress-starter && cd vuepress-starter<\/code><\/pre>\n
        \n
      1. Inizializziamo con il nostro gestore di pacchetti preferito. Per questo articolo, usiamo Yarn:<\/li>\n<\/ol>\n
        yarn init<\/code><\/pre>\n
          \n
        1. Installiamo VuePress nel progetto come developer dependency:<\/li>\n<\/ol>\n
          yarn add -D vuepress<\/code><\/pre>\n
            \n
          1. Creiamo una cartella docs<\/strong> per contenere tutto il codice e poi creiamo un file README.md<\/strong>, che serve come file di indice del progetto, simile a index.html<\/strong>:<\/li>\n<\/ol>\n
            mkdir docs && echo '# Hello VuePress' > docs\/README.md<\/code><\/pre>\n
              \n
            1. Apriamo il progetto in un editor di codice e aggiungiamo i seguenti script al file package.json<\/strong> in modo da poter servire e ed eseguire la build del sito:<\/li>\n<\/ol>\n
              \"scripts\": {\n    \"dev\": \"vuepress dev docs\",\n    \"build\": \"vuepress build docs\"\n  },<\/code><\/pre>\n
              A questo punto possiamo servire il sito eseguendo il comando yarn dev<\/code>. VuePress avvier\u00e0 il server di sviluppo all’indirizzo http:\/\/localhost:8080.<\/p>\n
              \"Tema<\/a>
              Tema predefinito per l’installazione manuale di VuePress.<\/figcaption><\/figure>\n
              Abbiamo creato un sito di documentazione. Noterete che VuePress offre un tema predefinito pulito e minimalista. Tuttavia, \u00e8 altamente personalizzabile e vi d\u00e0 la libert\u00e0 di creare un aspetto unico per il vostro sito web.<\/p>\n
              Creare pagine di documentazione<\/h2>\n
              VuePress segue una struttura di directory semplice per organizzare la documentazione. All’interno della cartella del progetto, troverete la cartella docs<\/strong> che abbiamo creato, dove potrete creare file Markdown<\/a> (.md<\/code>) per le vostre pagine di documentazione.<\/p>\n
              Ad esempio, potete creare file come getting-started.md<\/strong>, usage.md<\/strong> e troubleshooting.md<\/strong>. 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.<\/p>\n
              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<\/strong> e organizzarla con guide specifiche come using-kinsta-stsh.md<\/strong>. Se utilizzate questa struttura, il contenuto di using-kinsta-stsh.md<\/strong> diventa accessibile tramite un URL come http:\/\/localhost:8080\/guide\/using-kinsta-stsh.<\/p>\n
              Potete anche creare un file README.md<\/strong> o index.md<\/strong> nella cartella principale guide<\/strong>. Questo file funger\u00e0 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.<\/p>\n
              In questo repository di esempio di VuePress<\/a>, 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.<\/p>\n
              Personalizzare l’aspetto di VuePress<\/h2>\n
              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\u00f9 semplice e organizzato.<\/p>\n
              Per personalizzare l’aspetto e la navigazione del sito, create una cartella .vuepress<\/strong> nella directory principale del progetto. Questa cartella conterr\u00e0 i file di configurazione e le risorse relative al vostro sito VuePress.<\/p>\n
              Configurazione della navigazione<\/h3>\n
              Nella cartella .vuepress<\/strong>, creiamo un file config.js<\/strong>. Potete anche utilizzare altri formati di file come YAML (.yml), TOML (.toml) o TypeScript (.ts) per la vostra configurazione.<\/p>\n
              Nel file config.js<\/strong> potete definire la struttura di navigazione del sito utilizzando l’oggetto themeConfig<\/code>. Ecco un esempio di configurazione:<\/p>\n
              module.exports = {\n    title: 'Kinsta Vuepress',\n    description: 'A VuePress QuickStart for Kinsta',\n    themeConfig: {\n        nav: [\n            {\n                text: 'Guide',\n                link: '\/guide\/',\n            },\n            {\n                text: 'Static Site Hosting',\n                link: 'https:\/\/sevalla.com\/static-site-hosting\/',\n            },\n        ],\n        sidebar: {\n            '\/guide\/': [\n                {\n                    title: 'Guide',\n                    collapsable: false,\n                    children: ['', 'using-kinsta-stsh'],\n                },\n            ],\n        },\n    },\n};<\/code><\/pre>\n
              In questo esempio, stiamo configurando le sezioni title<\/code> e description<\/code> del sito, definendo i collegamenti di navigazione e impostando una barra laterale per la sezione \/guide\/<\/code>.<\/p>\n
              L’array nav<\/code> 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, \u00e8 configurato per la sezione \/guide\/<\/code>.<\/p>\n
              Potete leggere ulteriori informazioni sulla configurazione della barra laterale<\/a> nella documentazione di VuePress.<\/p>\n
              Stilizzazione<\/h3>\n
              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<\/strong> nella cartella .vuepress<\/strong><\/p>\n
              Per applicare semplici modifiche allo stile del preset predefinito o per definire alcune variabili da utilizzare in seguito, potete creare un file palette.styl<\/strong> in .vuepress\/styles<\/strong>. Queste sono alcune variabili predefinite che potete modificare:<\/p>\n
              \/\/ colors\n$accentColor = #5333ED\n$textColor = #2c3e50\n$borderColor = #eaecef\n$codeBgColor = #282c34\n$arrowBgColor = #ccc\n$badgeTipColor = #42b983\n$badgeWarningColor = darken(#ffe564, 35%)\n$badgeErrorColor = #DA5961\n\n\/\/ layout\n$navbarHeight = 3.6rem\n$sidebarWidth = 20rem\n$contentWidth = 740px\n$homePageWidth = 960px\n\n\/\/ responsive breakpoints\n$MQNarrow = 959px\n$MQMobile = 719px\n$MQMobileNarrow = 419px<\/code><\/pre>\n
              Queste 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\u00f2 creare un file index.styl<\/strong> nella cartella .vuepress\/styles<\/strong> dove utilizzare la normale sintassi CSS<\/a>:<\/p>\n
              .content {\n  font-size 30px\n}<\/code><\/pre>\n
              Per saperne di pi\u00f9 sullo stile di VuePress<\/a>, consultate la documentazione ufficiale.<\/p>\n
              Usare i componenti<\/h3>\n
              VuePress supporta l’uso di componenti per migliorare la funzionalit\u00e0 e l’aspetto delle vostre pagine. Potete creare componenti Vue e includerli nei vostri file Markdown. Create un componente components in .vuepres<\/strong> e tutti i file *.vue<\/code> che si trovano in .vuepress\/components<\/strong> verranno automaticamente registrati come componenti globali.<\/p>\n
              Ad esempio, consideriamo la creazione di due componenti, HomeOptions.vue<\/strong> e HostingBanner.vue<\/strong>:<\/p>\n
              .\n\u2514\u2500 .vuepress\n   \u2514\u2500 components\n      \u251c\u2500 HomeOptions.vue\n      \u2514\u2500 HostingBanner.vue<\/code><\/pre>\n
              All’interno di questi file di componenti vue.js, possiamo aggiungere codici CSS. Aggiungiamo il codice ai componenti HomeOptions.vue<\/strong> e HostingBanner.vue<\/strong>.<\/p>\n
              Aggiungiamo il codice sottostante a HomeOptions.vue<\/strong>:<\/p>\n
              <template>\n    <div class=\"options\">\n        <div class=\"option\">\n            <a\n                href=\"https:\/\/docs.sevalla.com\/templates\/overview\"\n                target=\"_blank\"\n            >\n                <h3>Quick Start Examples<\/h3>\n            <\/a>\n            <p>Explore quick start examples for setting up static sites.<\/p>\n        <\/div>\n        <div class=\"option\">\n            <a\n                href=\"https:\/\/docs.sevalla.com\/static-sites\/overviewgetting-started-static-site-hosting\/\"\n                target=\"_blank\"\n            >\n                <h3>Getting Started<\/h3>\n            <\/a>\n            <p>Learn how to get started with static site hosting.<\/p>\n        <\/div>\n        <div class=\"option\">\n            <a\n                href=\"https:\/\/docs.sevalla.com\/static-sites\/overviewmanage-static-sites\/\"\n                target=\"_blank\"\n            >\n                <h3>Manage Static Sites<\/h3>\n            <\/a>\n            <p>Discover how to efficiently manage your static sites.<\/p>\n        <\/div>\n    <\/div>\n<\/template>\n\n<style scoped>\n    a {\n        color: #2c3e50;\n    }\n    a:hover {\n        color: #5333ed;\n    }\n    .options {\n        display: flex;\n        gap: 10px;\n        margin: 40px 0;\n    }\n    .option {\n        border: 2px solid #eaecef;\n        border-radius: 5px;\n        padding: 10px;\n    }\n<\/style><\/code><\/pre>\n
              Inoltre, aggiungiamo il codice sottostante a HostingBanner.vue<\/strong>:<\/p>\n
              <template>\n    <div class=\"banner\">\n        <p>Host Your Static Site With Kinsta for Free!<\/p>\n        <a\n            href=\"https:\/\/docs.sevalla.com\/static-sites\/overview\"\n            target=\"_blank\"\n            class=\"btn\"\n            >Read More<\/a\n        >\n    <\/div>\n<\/template>\n\n<style> scoped>\n    .banner {\n        background: rgb(156, 85, 34);\n        background: linear-gradient(\n            90deg,\n            rgba(156, 85, 34, 1) 0%,\n            rgba(32, 50, 103, 1) 42%,\n            rgba(13, 18, 25, 1) 69%,\n            rgba(22, 47, 60, 1) 100%\n        );\n        color: #fff;\n        padding: 20px;\n        border-radius: 5px;\n        display: flex;\n        justify-content: center;\n        align-items: center;\n        flex-direction: column;\n    }\n    .banner p {\n        width: 600px;\n        font-size: 40px;\n        font-weight: bold;\n        text-align: center;\n        line-height: 50px;\n    }\n    .banner .btn {\n        border-radius: 5px;\n        padding: 15px;\n        color: #1f1f1f;\n        font-weight: bold;\n        background: #fff;\n        display: inline-block;\n        margin-bottom: 10px;\n    }\n    .banner .btn:hover {\n        background: #111319;\n        color: #fff;\n    }\n<\/style><\/code><\/pre>\n
              All’interno di qualsiasi file Markdown, possiamo utilizzare direttamente i componenti (i nomi vengono dedotti dai nomi dei file):<\/p>\n
              <HomeOptions\/>\n<HostingBanner\/><\/code><\/pre>\n
              Per saperne di pi\u00f9 sui componenti in VuePress<\/a>, consultate la documentazione.<\/p>\n
              Personalizzare la homepage<\/h3>\n
              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<\/code> e includere alcuni metadati aggiuntivi nel frontmatter YAML del file README.md<\/strong> principale.<\/p>\n
              Ecco un esempio di frontmatter YAML:<\/p>\n
              ---\nhome: true\nheroImage: \/hero.png\nheroText: Hero Title\ntagline: Hero subtitle\nactionText: Get Started \u2192\nactionLink: \/guide\/\nfeatures:\n- title: Simplicity First\n  details: Minimal setup with markdown-centered project structure helps you focus on writing.\n- title: Vue-Powered\n  details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.\n- title: Performant\n  details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.\nfooter: MIT Licensed | Copyright \u00a9 2018-present Evan You\n---<\/code><\/pre>\n
              Tutte queste configurazioni fanno s\u00ec che l’homepage della documentazione abbia l’aspetto seguente:<\/p>\n
              \"Homepage<\/a>
              Homepage predefinita di VuePress.<\/figcaption><\/figure>\n
              Vale la pena notare che \u00e8 possibile disabilitare i valori heroText<\/code> e tagline<\/code> o qualsiasi altro valore impostando i campi corrispondenti a null<\/code> se preferite un layout pi\u00f9 semplice o non includerlo. Qualsiasi contenuto incluso dopo il frontmatter YAML (cio\u00e8 la sezione dei metadati) sar\u00e0 trattato come un normale Markdown e sar\u00e0 reso dopo la sezione delle caratteristiche.<\/p>\n
              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\u00e0 nella visualizzazione dei contenuti del footer. Ecco un esempio di come impostare un footer ricco di testo:<\/p>\n
              ---\nhome: true\n---\n\n::: slot footer\nMade with \u2764\ufe0f by Kinsta. [Static Site Hosting](https:\/\/sevalla.com\/static-site-hosting\/)\n:::<\/code><\/pre>\n
              In questo caso, il contenuto della sezione ::: slot footer<\/code> permette di includere link e informazioni aggiuntive nell’area del footer della homepage.<\/p>\n
              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:<\/p>\n
              ---\nhome: true\ntagline: A VuePress QuickStart for Kinsta\nactionText: Quick Start \u2192\nactionLink: \/guide\/\n---\n\n<HomeOptions\/>\n<HostingBanner\/>\n\n::: slot footer\nMade with \u2764\ufe0f by Kinsta. [Static Site Hosting](https:\/\/sevalla.com\/static-site-hosting\/)\n:::<\/code><\/pre>\n
              \"Utilizzare<\/a>
              Utilizzare i componenti nella homepage di VuePress.<\/figcaption><\/figure>\n
              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.<\/p>\n
              Potete leggere ulteriori informazioni sulla personalizzazione del tema predefinito<\/a> nella documentazione.<\/p>\n
              Creare una sezione blog con VuePress<\/h2>\n
              Aggiungere una sezione blog al vostro sito VuePress \u00e8 un gioco da ragazzi perch\u00e9 VuePress permette di scrivere componenti Vue personalizzati che possono essere inseriti in qualsiasi file Markdown. Creiamo un componente che restituir\u00e0 l’elenco dei post del blog.<\/p>\n
              Creiamo un file BlogIndex.vue<\/strong> nella cartella components<\/strong> e aggiungiamo il seguente codice:<\/p>\n
              <template>\n    <div>\n        <div v-for=\"post in posts\" v-bind:key=\"post.path\">\n            <h2>\n                <router-link> :to=\"post.path\">{{ post.frontmatter.title }}<\/router-link>\n            <\/h2>\n            <p>{{ post.frontmatter.description }}<\/p>\n            <p><router-link> :to=\"post.path\">Read more<\/router-link><\/p>\n        <\/div>\n    <\/div>\n<\/template>\n\n<script>>\n    export default {\n        computed: {\n            posts() {\n                return this.$site.pages\n                    .filter(\n                        (x) => x.path.startsWith('\/blog\/') && !x.frontmatter.blog_index\n                    )\n                    .sort(\n                        (a, b) =>\n                            new Date(b.frontmatter.date) - new Date(a.frontmatter.date)\n                    );\n            },\n        },\n    };\n<\/script><\/code><\/pre>\n
              Nel frammento di codice fornito, definiamo un modello Vue che scorre i post del blog utilizzando v-for<\/code>, mostrando il titolo del post, la descrizione e un link “Leggi di pi\u00f9” per ogni post.<\/p>\n
              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\/<\/code>) e all’assenza di un attributo frontmatter blog_index<\/code>. Vengono poi ordinati per data in ordine decrescente per presentare prima i post pi\u00f9 recenti.<\/p>\n
              Quando creerete nuovi post sul blog, dovrete specificare la data del post come parte delle informazioni di frontmatter. Questo vi aiuter\u00e0 a ordinare i post in modo da far apparire per primi quelli pi\u00f9 recenti.<\/p>\n
              Per archiviare i post del blog, creiamo una cartella denominata blog<\/strong> nella root del progetto. In questa cartella, aggiungiamo un file README.md<\/strong>. Questo sar\u00e0 l’indice del blog ed \u00e8 qui che includeremo il componente BlogIndex<\/code> per elencare tutti i post del blog.<\/p>\n
              ---\nblog_index: true\n---\n\n# Blog\n\nWelcome To Our Blog\n\n<BlogIndex \/><\/code><\/pre>\n
              Assicuratevi di aggiungere l’attributo blog_index<\/code> frontmatter, in quanto \u00e8 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\u00e0 posts computed del componente BlogIndex.vue<\/strong>.<\/p>\n
              Quindi, creiamo una cartella blog nella root del progetto che memorizzer\u00e0 tutti i post del blog e creer\u00e0 ogni post. Ad esempio, creiamo un file first-post.md<\/strong> e aggiungiamo il seguente contenuto markdown:<\/p>\n
              ---\ntitle: \"My Exciting VuePress Blog Journey\"\ndate: 2023-09-28\ndescription: \"Exploring VuePress, a versatile static site generator, and sharing my experiences along the way.\"\n---\n\n# My Exciting VuePress Blog Journey\n\nIn 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.<\/code><\/pre>\n
              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.<\/p>\n
              \"Aggiungere<\/a>
              Aggiungere un blog a VuePress.<\/figcaption><\/figure>\n
              Infine, potete aggiungere la navigazione del blog alla navbar nel file .vuepress\/config.js<\/strong>:<\/p>\n
              nav: [\n            {\n                text: 'Guide',\n                link: '\/guide\/',\n            },\n            { text: 'Blog', link: '\/blog\/' },\n            {\n                text: 'Static Site Hosting',\n                link: 'https:\/\/sevalla.com\/static-site-hosting\/',\n            },\n        ],<\/code><\/pre>\n
              Potete fare molto di pi\u00f9 con VuePress, ad esempio aggiungere dei plugin<\/a>, utilizzare un tema separato<\/a> o addirittura creare un tema personale<\/a>.<\/p>\n
              Distribuire un sito statico VuePress su Kinsta<\/h2>\n
              Kinsta vi permette di ospitare fino a 100 siti web statici<\/a> gratuitamente<\/strong>. Potete farlo inviando il codice al vostro provider Git preferito (Bitbucket<\/a>, GitHub<\/a> o GitLab<\/a>) e poi distribuendolo su Kinsta.<\/p>\n
              Prima di inviare i vostri file a qualsiasi provider Git, create un file .gitignore<\/a> nella root del progetto per specificare i file e le cartelle che Git deve ignorare quando invia il vostro codice:<\/p>\n
              # dependencies\n\/node_modules\n\n# build directory\n.\/docs\/.vuepress\/dist\n\/public<\/code><\/pre>\n