Dopo il precedente articolo su VitePress 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 file markdown 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 sezione hero della pagina index.md:
hero:
image:
src: /BigLogo.png
alt: Logo
name: "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-config
export default defineConfig({
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.js
import DefaultTheme from 'vitepress/theme'
import './custom.css'
export default DefaultTheme
// .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’opzione base in .vitepress/config.js. Per esempio se il vostro sito è accessibile all’URL https://foo.github.io/bar/ allora base 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.js
import { defineConfig } from 'vitepress'
export default defineConfig({
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.js
import { defineConfig } from 'vitepress'
export default defineConfig({
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 a Mermaid per i grafici è necessario come prima cosa aggiungere il plugin:
npm i vitepress-plugin-mermaid
e poi modificare la configurazione come segue:
// .vitepress/config.js
import { defineConfig } from "vitepress";
import { withMermaid } from "vitepress-plugin-mermaid";
export default withMermaid(
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 su https://simpleicons.org/. Se non fossero sufficienti è possibile usare qualunque immagine in formato SVG (per esempio da https://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.js
export default {
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 su GitHub per poterla modificare:
// .vitepress/config.js
export default {
lastUpdated: true,
themeConfig: {
editLink: {
pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path'
}
}
}
Top comments (0)