Ga naar inhoud

SVG exporteren

vsa svg, vsa process en vsa build-markdown renderen VSA-notatie naar SVG — een schaalbare vectorafbeelding die je inline toont naast gewone tekst, op scherm of afdruk. Dit is de meest gebruikte workflow: geen externe player nodig, werkt zonder JavaScript, en schaalt scherp op elk scherm.

Voor afspelen/oefenen gebruik je in plaats daarvan MusicXML/.mxl.

Wanneer gebruik je SVG?

Situatie Gebruik SVG?
Notatie tonen naast liturgische tekst (web of print) Ja
Consistente weergave op elk apparaat Ja
Afdrukbaar boek/deel (A4, @media print) Ja
Audio afspelen of oefenen Nee — gebruik vsa musicxml
Bewerken in MuseScore Nee — gebruik vsa musicxml met profiel engraving

Drie manieren om SVG te genereren

Commando Wanneer
vsa svg Eén los .vsa-bestand snel als afbeelding bekijken.
vsa process SVG's uit VSA-blokken in Markdown, zonder de Markdown te herschrijven.
vsa build-markdown Hugo-publicatie: Markdown en SVG-assets in één stap (inline rendering).

Voor een losse controle tijdens het schrijven is vsa svg het snelst. Voor een echte publicatie (Hugo-site) gebruik je vsa build-markdown, dat de ::: vsa-notatie … :::-blokken in je Markdown automatisch vervangt door een verwijzing naar de gegenereerde SVG (zie "Inline rendering via build-markdown" hieronder).

Snel starten

Eén geldige frase bekijken (examples\docs-walkthroughs\svg-phrase-kort.vsa):

[:] {/Hei_}{/lig_} is de Heer. [//:]

cd /d C:\Git\orthodox-ronl\VSA-tooling
vsa svg examples\docs-walkthroughs\svg-phrase-kort.vsa generated\vsa\svg-phrase-kort.svg

SVG geschreven naar: generated\vsa\svg-phrase-kort.svg

Korte VSA-frase als SVG

Langere frase + regelbreedte

Zelfde start, langere tekst (examples\docs-walkthroughs\svg-phrase-lang.vsa), met smallere --max-line-width zodat de renderer afbreekt:

vsa svg examples\docs-walkthroughs\svg-phrase-lang.vsa generated\vsa\svg-phrase-lang.svg --max-line-width 400

Langere VSA-frase, afgebroken SVG

SVG's uit een map met Markdown, zonder Hugo-Markdown te genereren (levert o.a. toon-1-block-1.svg en toon-2-block-1.svg):

vsa process examples\site-demo generated\vsa

Volledige Hugo-publicatie (Markdown + SVG-assets):

vsa build-markdown examples\consumer-minimal\content-source generated\content generated\static\vsa

Zie de man-pagina's voor de volledige argumentenlijst, opties en foutgevallen: cli/svg.md, cli/process.md, cli/build-markdown.md.

Preview-SVG's in deze docs regenereren (na wijziging van de bron-.vsa):

python scripts\sync-docs-walkthrough-svgs.py

Inline rendering via build-markdown

vsa build-markdown vervangt in de gegenereerde Markdown elk VSA-blok door een verwijzing naar de gegenereerde SVG. Bron-Markdown:

::: vsa-notatie
[:] {/Hei_}{/lig_} is de Heer. [:]
:::

wordt, met --output-mode img (default), een gewone <img>-tag:

<img class="vsa-notation" src="/vsa/smoke-block-1.svg" alt="VSA notatie">

of, met --output-mode shortcode, een Hugo-shortcode:

{{< vsa src="/vsa/smoke-block-1.svg" >}}

Kies shortcode als je in de consumer-site meer controle wilt over hoe de SVG wordt ingebed (bijv. lazy-loading, wrapper-<div>, of print-specifieke opmaak via layouts\shortcodes\vsa.html); kies img als je geen aangepaste Hugo-shortcode wilt onderhouden.

Bestandspad versus URL-pad: assets_dir en --assets-url-prefix

Dit onderscheid is de meest voorkomende bron van verwarring bij build-markdown:

Soort Argument/optie Voorbeeldwaarde Betekenis
Bestandspad assets_dir (positioneel) generated\static\vsa Waar de tool de SVG's op schijf schrijft.
URL-pad --assets-url-prefix /vsa Wat er in de gegenereerde <img src="…">/shortcode terechtkomt.

Deze twee zijn onafhankelijk: assets_dir bepaalt alleen waar bestanden komen te staan, --assets-url-prefix bepaalt alleen de tekst die in de Markdown/HTML verschijnt. Ze moeten wél op elkaar aansluiten zodra Hugo de site publiceert:

assets_dir:            generated\static\vsa
                                 ↓ (Hugo publiceert static\ als site-root)
publieke URL:           https://mijn-site/vsa/smoke-block-1.svg
--assets-url-prefix:    /vsa

Als --assets-url-prefix niet overeenkomt met waar Hugo assets_dir publiceert (meestal de static\vsa-submap van de Hugo-site), tonen afbeeldingen niet — de SVG-bestanden bestaan wel, maar de link in de HTML wijst naar de verkeerde plek.

Default-waarden staan (net als max-line-width en output-mode) in vsa.toml; zie config.md voor de voorrangsregel (CLI-optie → vsa.toml → interne default).

Waar komen de gegenereerde bestanden terecht?

SVG's die je met vsa svg, vsa process of vsa build-markdown genereert, zijn afgeleide bestanden uit de .vsa-bron en horen niet gecommit te worden naast de bron. Gebruik lokaal een map als generated\ (of tmp\) die in .gitignore staat:

mijn-repo/
  content/                   # of content-source/ — VSA-bron (wél in git)
    voorbeeld.md
  generated/                 # SVG- en Markdown-output (niet in git)
    static\vsa\voorbeeld-block-1.svg
    content\voorbeeld.md

In een Hugo-consumer-site komt de assets_dir overeen met de static\vsa-map van die site (zie consumer-site.md en reuse-vsa-tooling.md voor het volledige build-in-CI-voorbeeld). In de bron-repository zelf worden geen afgeleide SVG's opgeslagen — daar staat alleen de .vsa-bron (zie repo-structuur en het derived/-concept daar voor build-output dat nooit in git komt).

Diagnose bij problemen

Symptoom Controle
Commando faalt met validatiefout Draai vsa validate op de invoer voor de exacte foutlocatie.
SVG ziet er raar uit Controleer --max-line-width; bewaar het voorbeeld eventueel als regressiecase.
Afbeelding niet zichtbaar in Hugo Controleer of --assets-url-prefix aansluit op waar Hugo assets_dir publiceert (zie boven).
Shortcode zichtbaar als tekst Controleer of layouts\shortcodes\vsa.html bestaat in de consumer-site.
Oude SVG's blijven zichtbaar Verwijder de output-map (generated\…) en bouw opnieuw.

Zie ook