2
0
mirror of https://github.com/VinylDNS/vinyldns synced 2025-08-22 10:10:12 +00:00
2024-08-12 18:06:53 +05:30
..
2021-11-02 17:06:24 -04:00
2021-10-21 14:21:37 -04:00

VinylDNS documentation site

https://www.vinyldns.io/

Publication

The VinylDNS documentation is published to the gh-pages branch after each successful master branch build. This is configured through Travis CI.

Documentation Structure

  • The documentation site is built with the sbt-microsites plugin.
  • The docs module contains most content for the documentation site:
    • The text content is in the src/main/mdoc directory
    • The primary menu is built through setting a position value in the linked file src/main/modc/index.md
    • The sidebar menu is maintained in the src/main/resources/microsite/data/menu.yml file
    • Images are stored in /src/main/resources/microsite/img/ directory
    • Custom CSS is stored in the src/main/resources/microsite/css/custom.css file
  • The Contributing Guide is the CONTRIBUTING.md file at the root of the VinylDNS project.
  • The sbt-microsite configuration is in the docSettings section of the build.sbt in the root of the VinylDNS project.

Build with Docker

To build with Docker, from the modules/docs director you can run make. This will provide you with a prompt in a container that is configured with all of the prerequisites and the /build directory will be mapped to the VinylDNS root directory. From there you can follow the [steps below](#Build Locally).

Example:

$ make
root@1e7375bec453:/build# sbt
sbt:root> project docs
[info] set current project to docs (in build file:/build/)
sbt:docs> makeMicrosite

Build Locally

To build the documentation site you will need Jekyll 4.0+ installed. This is installed by default in the [Docker container](#Build with Docker).

In the terminal enter:

  1. sbt
  2. project docs
  3. makeMicrosite

In a separate tab enter:

  1. cd modules/docs/target/site
  2. jekyll serve --host 0.0.0.0
    • By default jekyll listens on 127.0.0.1 which will cause problems whe using Docker, so we specify that it should listen on interfaces by providing --host 0.0.0.0
  3. View in the browser at http://localhost:4000/
    • Note: port 4000 is mapped to localhost by the Docker container as well

Tips:

  • If you make any changes to the documentation you'll need to run makeMicrosite again. You don't need to restart Jekyll.
  • If you only need to build the microsite once you can run sbt ";project docs ;makeMicrosite" then follow the jekyll steps from the same tab. -If you delete files you may need to stop Jekyll and delete the target directory before running makeMicrosite again to see the site as expected locally.