Dopo ilprecedente articolo suVitePress mi sono state fatte un po' di domande su come configurarlo e come attivare alcune funzionalità specifiche. Approfitto di questo spazio per raccogliere i miei appunti. Per ogni voce ho messo il link alla guida ufficiale per approfondire.
Dove posizionare immagini e altri asset
Le immagini o altri asset referenziate all'interno dei filemarkdown dovrebbero sempre essere indicate tramite un path relativo:
VitePress si occuperà in fase di build di metterli nel posto giusto. Se invece si desidera caricare un file che non viene usato da nessun markdown nella root del sito (es. robot.txt, favicon, ecc.) deve essere posizionato nella directory./docs/public.
https://vitepress.dev/guide/asset-handling#referencing-static-assets
Logo
È possibile inserire un logo a destra della pagina andando a modificare la sezionehero della paginaindex.md:
hero:image:src:/BigLogo.pngalt:Logoname:"MyApp"L’immagine deve essere inserita nella directory./docs/public e dovrebbe essere di almeno 192x192 pixel.
https://vitepress.dev/reference/default-theme-home-page#hero-section
Un logo più piccolo può essere messo in alto a sinistra su tutte le pagine andando a modificare la configurazione.vitepress/config.js:
import{defineConfig}from'vitepress'// https://vitepress.dev/reference/site-configexportdefaultdefineConfig({themeConfig:{logo:"/small-logo.png",}});https://vitepress.dev/reference/default-theme-nav#site-title-and-logo
Come personalizzare i CSS
Per personalizzare i colori o altre caratteristiche estetiche del sito è possibile modificare il tema aggiungendo un CSS custom.
// .vitepress/theme/index.jsimportDefaultThemefrom'vitepress/theme'import'./custom.css'exportdefaultDefaultTheme//.vitepress/theme/custom.css:root{--vp-c-brand-1:#d65a4a;--vp-c-brand-2:#005d97;}https://vitepress.dev/guide/extending-default-theme
Base URL
Se il sito verrà messo in un URL che non è la root del sito è necessario indicarlo nell’opzionebase in.vitepress/config.js. Per esempio se il vostro sito è accessibile all’URLhttps://foo.github.io/bar/ allorabase deve essere uguale a/base/ (deve sempre iniziale con slash).
https://vitepress.dev/guide/asset-handling#base-url
Ricerca integrata nel sito
Se si desidera attivare una barra di ricerca è sufficiente inserire in configurazione:
// .vitepress/config.jsimport{defineConfig}from'vitepress'exportdefaultdefineConfig({themeConfig:{search:{provider:'local'}}})In questo modo la ricerca è fatta localmente, se la documentazione fosse molto estesa è preferibile usare un sito esterno. VitePress si integra perfettamente con Algolia.
Vedi:https://vitepress.dev/reference/default-theme-search#algolia-search
Inserire la favicon
Il modo più semplice per aggiungere una favicon è copiarla della directory./docs/public/ e aggiungere questa configurazione:
// .vitepress/config.jsimport{defineConfig}from'vitepress'exportdefaultdefineConfig({head:[["link",{rel:"icon",href:"/favicon.ico"}]],})https://vitepress.dev/reference/site-config#example-adding-a-favicon
Aggiungere il supporto a Mermaid
Se si vuole aggiungere il supporto aMermaid per i grafici è necessario come prima cosa aggiungere il plugin:
npm i vitepress-plugin-mermaide poi modificare la configurazione come segue:
// .vitepress/config.jsimport{defineConfig}from"vitepress";import{withMermaid}from"vitepress-plugin-mermaid";exportdefaultwithMermaid(defineConfig({title:"...",...}));Icone social personalizzate
In alto a destra sul sito sono presenti le icone per i social; è possibile aggiungerle modificando la configurazione:
socialLinks:[{icon:'github',link:'https://github.com/foo/bar'},{icon:'youtube',link:'https://youtube.com/foo/'},]Le icone utilizzabili sono tutte quelle presenti suhttps://simpleicons.org/. Se non fossero sufficienti è possibile usare qualunque immagine in formato SVG (per esempio dahttps://iconify.design/) in questo modo:
socialLinks:[{icon:'github',link:'https://github.com/EtheaDev/SVGIconImageList'},{icon:{svg:'<svg xmlns="http://www.w3.org/2000/svg" width="0.86em" height="1em" viewBox="0 0 440 512"> <path fill="currentColor" d="m188.1 318.863l-4.04-19.052l176.073-121.468l17.315 102.649zm151.193 148.26c-2.721 27.2-50.315 44.877-50.315 44.877l-84.315-183.43l25.839-4.08c40.831 49.843 85.165 50.51 108.79 142.634m-104.804 1.518c-35.834-7.263-63.108-9.73-83.65-9.73c-23.054 0-37.62 3.113-46.232 6.055l25.603-58.769l.093-.235c.097-.237 10.483-22.743 96.55-9.58l21.537 46.854zM80.649 223.858L31.276 126.47l53.036-53.036l24.478 108.112c-10.555 11.244-19.887 25.468-28.143 42.312m225.327-76.99l133.271-111.51L339.293 0l-94.77 129.473c20.274 2.15 43.096 10.268 61.453 17.396m-70.014-18.04L310.056 0h-96.552l-39.438 138.028c19.386-6.797 40.046-9.782 61.896-9.2m-68.695 11.24l14.279-118.99l-76.835 31.958l10.84 121.93c13.401-12.673 29.885-24.51 51.716-34.898m-97.69 190.4L4.08 310.055l14.958 44.876h58.296a165 165 0 0 1-7.756-24.465m11.112 32.175l-49.412 7.247l23.458 34.678l39.6-18.029a165 165 0 0 1-13.646-23.896M65.275 277.34L4.08 237.98L0 293.736l66.985 22.984c-1.661-12.666-2.19-25.81-1.71-39.38m8.838-43.44L25.84 165.648L4.08 218.941l61.196 52.28zm47.339 171.971c8.036-25.69 61.777-23.832 101.328-18.352l-28.32-61.61l-12.668 2.534l-6.84-32.263l163.834-113.023C234.333 93 146.248 154.418 115 187.667c-41.667 44.333-72.667 138 6.452 218.205" /></svg>'},link:'https://github.com/EtheaDev/SVGIconImageList'}]https://vitepress.dev/reference/default-theme-config#sociallinks
Footer
Inoltre è possibile inserire un footer personalizzato in home page in questo modo:
// .vitepress/config.jsexportdefault{themeConfig:{footer:{message:'Released under the MIT License.',copyright:'Copyright © 2024-present Luca Minuti'}}}Sulle singole pagine della documentazione è possibile inserire sia la data di ultima modifica della pagina stessa che il link alla pagina suGitHub per poterla modificare:
// .vitepress/config.jsexportdefault{lastUpdated:true,themeConfig:{editLink:{pattern:'https://github.com/vuejs/vitepress/edit/main/docs/:path'}}}Top comments(0)
For further actions, you may consider blocking this person and/orreporting abuse
