diff --git a/README.md b/README.md index 55dbf3cc0..e80d10b18 100644 --- a/README.md +++ b/README.md @@ -184,6 +184,11 @@ The documentation can be viewed via Docker: ```bash cd docs +./runDocker.sh +``` + +FYI: Alternative Docker command: +```bash docker run --rm -it --volume="$PWD:/srv/jekyll" --volume="$PWD/vendor/bundle:/usr/local/bundle" --env JEKYLL_ENV=production jekyll/jekyll:3.8 jekyll build -V # Open docs/_site/index.html in your web browser to see the results. # (Note: The preview isn't perfect. Links that use the site.github.url variable won't work. diff --git a/docs/documentation.md b/docs/documentation.md new file mode 100644 index 000000000..2a9f98475 --- /dev/null +++ b/docs/documentation.md @@ -0,0 +1,43 @@ +--- +layout: default +title: How to edit the documentation +--- + +# Working with the docs + +The website is a static website generated by Jekyll. + +The website is generated from the files in `$GIT/dnscontrol/docs`. If a file +has a `.md` extension, it will be turned into an HTML file. Otherwise it is +copied verbatium. + +# Directory Hierarchy + +* `docs`: The root directory. index.md is the homepage. +* `docs/_includes`: Functions and templates. +* `docs/css`: CSS +* `docs/_functions/record`: Things that augment a record. +* `docs/_functions/domain`: Things inside a `D()` +* `docs/_functions/global`: Features at the global (file) level. +* `docs/_layouts`: Main layout +* `docs/public`: Static content +* `docs/_site`: The generated site (not in Git) +* `docs/assets`: Static files +* `docs/flattener`: The SPF flatter + +# How to preview + +The documentation can be viewed via Docker: + +```bash +cd docs +./runDocker.sh +``` + +FYI: Alternative Docker command: + +```bash +docker run --rm -it --volume="$PWD:/srv/jekyll" --volume="$PWD/vendor/bundle:/ usr/local/bundle" --env JEKYLL_ENV=production jekyll/jekyll:3.8 jekyll build -V +# Open docs/_site/index.html in your web browser to see the results. +# (Note: The preview isn't perfect. Links that use the site.github.url variable won't work. +``` diff --git a/docs/getting-started.md b/docs/getting-started.md index d7dcc35c6..e4d519c46 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -11,16 +11,16 @@ title: Getting Started DNSControl can be built with Go version 1.18 or higher. -The `go get` command will download the source, compile it, and +The `go install` command will download the source, compile it, and install `dnscontrol` in your `$GOBIN` directory. To install, simply run - GO111MODULE=on go get github.com/StackExchange/dnscontrol/v3 + go install github.com/StackExchange/dnscontrol/v3@latest To download the source - git clone github.com/StackExchange/dnscontrol + git clone https://github.com/StackExchange/dnscontrol If these don't work, more info is in [#805](https://github.com/StackExchange/dnscontrol/issues/805). @@ -51,7 +51,7 @@ simple tests anything will do. Create a subdirectory called `zones` in the same directory as the configuration files. (`mkdir zones`). `zones` is where the BIND provider writes the zonefiles it creates. Even if you don't -use BIND, it is useful for testing. +use BIND for DNS service, it is useful for testing. ## 3. Create the initial `dnsconfig.js` diff --git a/docs/index.md b/docs/index.md index a7ff5a492..404d1f90c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -207,6 +207,9 @@ title: DNSControl
  • Release Engineering: How to build and ship a release
  • +
  • + Edit Documentation: How to edit these docs +
  • Bring-Your-Own-Secrets: Automate tests