🚀
DNSControl
🚀
DNSControl
  • Introduction to DNSControl
  • Getting Started
    • Overview
    • Examples
    • Migrating zones to DNSControl
    • TypeScript autocomplete and type checking
  • Language Reference
    • JavaScript DSL
    • Top Level Functions
      • D
      • DEFAULTS
      • DOMAIN_ELSEWHERE
      • DOMAIN_ELSEWHERE_AUTO
      • D_EXTEND
      • FETCH
      • HASH
      • IP
      • NewDnsProvider
      • NewRegistrar
      • PANIC
      • REV
      • REVCOMPAT
      • getConfiguredDomains
      • require
      • require_glob
    • Domain Modifiers
      • A
      • AAAA
      • ALIAS
      • AUTODNSSEC_OFF
      • AUTODNSSEC_ON
      • CAA
      • CAA_BUILDER
      • CNAME
      • DHCID
      • DNAME
      • DNSKEY
      • DISABLE_IGNORE_SAFETY_CHECK
      • DMARC_BUILDER
      • DS
      • DefaultTTL
      • DnsProvider
      • FRAME
      • HTTPS
      • IGNORE
      • IGNORE_NAME
      • IGNORE_TARGET
      • IMPORT_TRANSFORM
      • IMPORT_TRANSFORM_STRIP
      • INCLUDE
      • LOC
      • LOC_BUILDER_DD
      • LOC_BUILDER_DMM_STR
      • LOC_BUILDER_DMS_STR
      • LOC_BUILDER_STR
      • M365_BUILDER
      • MX
      • NAMESERVER
      • NAMESERVER_TTL
      • NAPTR
      • NO_PURGE
      • NS
      • PTR
      • PURGE
      • SOA
      • SPF_BUILDER
      • SRV
      • SSHFP
      • SVCB
      • TLSA
      • TXT
      • URL
      • URL301
      • Service Provider specific
        • Akamai Edge Dns
          • AKAMAICDN
        • Amazon Route 53
          • R53_ALIAS
        • Azure DNS
          • AZURE_ALIAS
        • Cloudflare DNS
          • CF_REDIRECT
          • CF_SINGLE_REDIRECT
          • CF_TEMP_REDIRECT
          • CF_WORKER_ROUTE
        • ClouDNS
          • CLOUDNS_WR
    • Record Modifiers
      • TTL
      • Service Provider specific
        • Amazon Route 53
          • R53_ZONE
          • R53_EVALUATE_TARGET_HEALTH
    • Why CNAME/MX/NS targets require a "dot"
  • Provider
    • Supported providers
    • Akamai Edge DNS
    • Amazon Route 53
    • AutoDNS
    • AXFR+DDNS
    • Azure DNS
    • Azure Private DNS
    • BIND
    • Bunny DNS
    • CentralNic Reseller (CNR) - formerly RRPProxy
    • Cloudflare
    • ClouDNS
    • CSC Global
    • deSEC
    • DigitalOcean
    • DNS Made Easy
    • DNSimple
    • DNS-over-HTTPS
    • DOMAINNAMESHOP
    • Dynadot
    • easyname
    • Exoscale
    • Gandi_v5
    • Gcore
    • Google Cloud DNS
    • Hetzner DNS Console
    • HEXONET
    • hosting.de
    • Huawei Cloud DNS
    • Hurricane Electric DNS
    • Internet.bs
    • INWX
    • Linode
    • Loopia
    • LuaDNS
    • Microsoft DNS Server on Microsoft Windows Server
    • Mythic Beasts
    • Namecheap
    • Name.com
    • Netcup
    • Netlify
    • NS1
    • OpenSRS
    • Oracle Cloud
    • OVH
    • Packetframe
    • Porkbun
    • PowerDNS
    • Realtime Register
    • RWTH DNS-Admin
    • Sakura Cloud
    • SoftLayer DNS
    • TransIP
    • Vultr
  • Commands
    • preview/push
    • check-creds
    • get-zones
    • get-certs
    • fmt
    • creds.json
    • Global Flag
    • Disabling Colors
  • Advanced features
    • CI/CD example for GitLab
    • CLI variables
    • Nameservers and Delegations
    • Notifications
    • Useful code tricks
    • JSON Reports
  • Developer info
    • Code Style Guide
    • Documentation Style Guide
    • DNSControl is an opinionated system
    • Writing new DNS providers
    • Creating new DNS Resource Types (rtypes)
    • Integration Tests
    • Test a branch
    • Unit Testing DNS Data
    • Bug Triage Process
    • Bring-Your-Own-Secrets for automated testing
    • Debugging with dlv
    • ALIAS Records
    • TXT record testing
    • DNS records ordering
  • Release
    • How to build and ship a release
    • Changelog v3.16.0
    • GitHub releases
Powered by GitBook
On this page
  • Where are the docs?
  • How to add a new page?
  • Top-of-Document parameters
  • GitHub pull request preview
  • How to access preview links
  • Formatting tips
  • General
  • Headings
  • Code Snippets
  • Hint
  • Example of a hint
  • Technical references
  • Links
  • Capitalization matters
  • Proofreading
Edit on GitHub
  1. Developer info

Documentation Style Guide

PreviousCode Style GuideNextDNSControl is an opinionated system

Last updated 5 months ago

Where are the docs?

TL;DR version: is the . is the website. (Yes, the names are backwards!)

The two websites

    • The main website

    • Source code:

    • Mostly "marketing" for the project.

    • Rarely changes. Updated via GitHub "pages" feature.

    • Project documentation

    • Source code:

    • Users and developer documentation

    • Changes frequently. Updated via

The directory structure

Within the git repo, docs are grouped:

  • : general docs

  • : One file per provider

  • : One file per dnsconfig.js language feature

  • : Images for page FOO(PNGs only, please!)

How to add a new page?

  1. Add the page to the documentation folder (possibly a sub folder)

  2. List the page in SUMMARY.md so that it will appear in the table of contents, sidebar, etc.

Top-of-Document parameters

Files in the documentation/language-reference/{record,domain,global} subdirectories have a header at the top that is used to populate other systems.

---
name: A
provider: NAMEDOTCOM
parameters:
  - name
  - address
  - modifiers...
parameter_types:
  name: string
  address: string | number
  "modifiers...": RecordModifier[]
---
  • name: The name of the function/constant in the document. This should match the filename (aside from the .md suffix).

  • parameters: These are the names of the parameters that the function accepts. modifiers... indicates that a variable number of modifiers can be added.

  • parameter_types: The typescript type for each parameter. This is used when generating types-dnscontrol.d.ts

  • provider: If a feature is only available for one provider

GitHub pull request preview

When you submit a GitHub pull request, you can view the result in advance. This allows you to check the impact of changes.

How to access preview links

For every pull request, you’ll see a status added to the GitHub pull request with a unique preview URL. Clicking the Details link on the status will take you to the preview URL for your content. You can then make sure the content is as expected.

NOTE: A new preview URL is created for every git update. Please check the GitHub status for the most up to date URL.

Formatting tips

General

Break lines every 80 chars.

Include a blank line between paragraphs.

Leave exactly one blank line before and after a heading.

JavaScript code should use double quotes (") for strings, not single quotes ('). They are equivalent but consistency is good.

Headings

#  Title of the page

## Heading

At least one paragraph.

## Subheadings

At least one paragraph.

* **Step 1: Foo**

Description of the step.

* **Step 2: Bar**

Description of the step.

(further sub sub headings are discouraged encouraged)

Code Snippets

See the examples below, for the Markdown syntax click on the 'Source code'.

Long example: (with filename)

dnsconfig.js
var REG_NONE = NewRegistrar("none");
var DNS_BIND = NewDnsProvider("bind");

D("example.com", REG_NONE, DnsProvider(DNS_BIND),
    A("@", "1.2.3.4"),
);

Long example: (without filename)

var REG_NONE = NewRegistrar("none");
var DNS_BIND = NewDnsProvider("bind");

D("example.com", REG_NONE, DnsProvider(DNS_BIND),
    A("@", "1.2.3.4")
);

Hint

Hints are a great way to bring the reader's attention to specific elements in your documentation.

There are 4 different types of hints, and both inline content and formatting are supported.

Example of a hint

Info hints are great for showing general information, or providing tips and tricks.

Success hints are good for showing positive actions or achievements.

Warning hints are good for showing important information or non-critical warnings.

Danger hints are good for highlighting destructive actions or raising attention to critical information.

This is a heading

This is a line

This is a second line

Technical references

Mentioning language features

Not every mention to A, CNAME, or function needs to be a link to the manual for that record type. However, the first mention on a page should always be a link. Others are at the authors digression.

The [`PTR`](language-reference/domain-modifiers/PTR.md) feature is helpful in LANs.

Mentioning functions from the Source code

The function `GetRegistrarCorrections()` returns...

Links

Internal links

Blah blah blah [M365_BUILDER](language-reference/domain-modifiers/M365_BUILDER.md)

NOTE: The .md is required.

Link to another website

Just list the URL.

Blah blah blah <https://www.google.com> blah blah.

Link with anchor text

Blah blah blah [a search engine](https://www.google.com) blah blah.

Capitalization matters

Please capitalize these terms as you see them here:

  • DNSControl

  • GitHub

Proofreading

Please spellcheck documents before submitting a PR.

Here's an example from

Don't be surprised if Tom rewrites your text. He often does that to keep the documentation consistent and make it more approachable by new users. It's not . Well, not usually.

docs
marketing website
documentation
docs.dnscontrol.org
https://dnscontrol.org/
docs
https://docs.dnscontrol.org/
documentation
GitBook
documentation/
documentation/provider/
documentation/language-reference/
documentation/assets/FOO/
A
Source code
Source code
Source code
Source code
Source code
Source code
because he has a big ego