Preview a Respec document - Geonovum/respec GitHub Wiki

Online previews

Respec documents are published on the web. If for a draft version the github.io platform is configured to publish pages from the Github repository, a preview of the current document in Github is always available online. Example: for the Github Repository Geonovum/whitepaper-standaarden, the preview is available at: https://geonovum.github.io/whitepaper-standaarden/.

Local preview: install a simpel webserver

Sometimes it is useful or required to be able to preview the Respec document on your local machine. For example if the Github repository is private and the github.io pages are not available. Respec documents are often not properly displayed if they are opened directly (as a file) in a webbrowser. Esepecially Markdown documents can't be loaded then.

A solution is to configure a local webserver to host the document. There are many options, but 2 are described here: a Python solution and installation (Windows machines) of tinyweb.

Python webserver

If Python (version 3, see Python website for downloads) is installed, it is easy to run a simple webserver on your machine.

  1. open a command prompt
  2. navigate to the directory of the Respec document on your machine (e.g. C:\Documents\SampleRespecDoc\ if SampleRespecDoc is the directory (and probably the name of the Github repository) where the Respec doc is
  3. run the following command: py -m http.server 8080
  4. Python starts a local webserver now on port 8080. Which means that the URL http://localhost:8080/ now serves the Resepc document from the directory C:\Documents\SampleRespecDoc\.

That's it.

Tinyweb webserver

For Windows machines, Tinyweb is a very easy and light webserver (executable) to serve documents from a directory.

  1. Go to https://www.ritlabs.com/en/products/tinyweb/download.php to download the executable.
  2. Unzip the file on your disk, e.g. C:\apps\tiny.exe
  3. Open a command prompt
  4. navigate to the directory of the Respec document on your machine (e.g. C:\Documents\SampleRespecDoc\ if SampleRespecDoc is the directory (and probably the name of the Github repository) where the Respec doc is
  5. run the following command: C:\apps\tiny.exe C:\Documents\SampleRespecDoc\
  6. Tinyweb starts a local webserver now on port 80. Which means that the URL http://localhost/ now serves the Resepc document from the directory C:\Documents\SampleRespecDoc\.

That's it.

See TinyWeb's documentation for more details.