Paikallisen esikatselun luominen

Fedora Documentation Team Last review: 2023-03-19
Paikallinen esikatselu on arvokas työkalu muutosten testaamiseen, kun työskentelet paikallisessa kirjoitusympäristössä. Aja docsbuilder-skripti, joka on saatavilla Fedora-sisältövarastossa. Voit rakentaa ja ajaa täysin renderöidyn sivuston koneellasi esitarkastellaksesi muutoksiasi ennen kuin teet pull-pyynnön Fedora-sisältövarastoihin.

Kun tarvitset paikallisen esikatselun

Kun työskentelet paikallisen luontiympäristön kanssa, paikallinen esikatselu tarjoaa monipuolisen työnkulun testata, miten muutokset renderöidään ja miten ne toimivat selaimessasi paikallisesti. Kun teet muutoksia, kuten, mutta ei rajoittuen;

  • Vaihda linkkejä tai korjaa rikkinäiset linkit

  • Muuta dokumentti ristiviittauksiksi xref-viittausten avulla

  • Yhdistä useita sivuja yhdeksi sivuksi

  • Päivitä kuvia tai korjaa rikkinäiset kuvat

  • Lisää metatietoja tai vaihtoehtoista tekstiä kuviin

  • Osiotasot järjestetty uudelleen (esim. h2–h3, h3–h4) luettavuuden ja lukukulun vuoksi

  • Korjaa passiivinen navigointipalkki

  • Reorganize navigation bar

  • Rewrite outdated pages

  • Add AsciiDoc attributes

  • Reiterate changes and tests with vale linter

you need build scripts to render the changes predictably and test them before you make a pull request.

What the scripts do

Yhtenäinen dokumenttien rakennusskripti, docsbuilder.sh, rakentaa sivustosta paikallisen version, joka tarkoittaa koko sivuston osajoukkoa, joka sijaitsee paikallisessa arkistossasi. Skripti puolestaan käynnistää web-palvelimen ja palvelee sivustoa osoitteessa http://localhost:8080/. Tämän linkin avaaminen millä tahansa web-selaimella näyttää esikatselun, joka on käytettävissä, kunnes lopetat prosessin (kbd:[Ctrl+C] terminaalissa).

Tarkista projektien aloitussivulta README.md-tiedosto suorittaaksesi ehdotetun skriptin.

Muutosten testaaminen

Go to the the directory where cloned repo is, build, watch and preview the site by running the build scripts in terminal.

$ ./docsbuilder.sh

Pagure or other content repositories display a different builder script.

$ ./builder.sh

To use the scripts you need Podman installed if using Fedora Linux or Docker CE if using macOS.

Previewing multiple repositories

If your work spans content in multiple repositories, e.g. because you link to another repository, you can extend the preview by adding more repositories to site.yml as follows:

content:
  sources:
  - url: .
    branches: HEAD
  - url: https://pagure.io/fedora-docs/another-repository.git
    branches: main

Correct entries to use can be found from docs-fp-o site.yml.

Using the regular Antora scripts

If you want to use the regular Antora build and preview workflow - follow the instructions on Antora Documentation page.

Once you have Antora CLI and Antora Site Generator you can build and preview the pages without the container scripts.

To build the pages in the project directory run:

antora generate site.yml

This will create a new directory public which contains all the necessary files. Navigate there and run a server command. You might already have a Python simple server, in which case run:

python3 -m http.server

or if you only have Python 2 on your machine:

python -m SimpleHTTPServer

It opens a local preview at port 8000.

If you have cargo (Rust package manager), you could also install and use miniserve or any other simple server of your choice for that matter.

Want to help? Learn how to contribute to Fedora Docs ›