Skip to main content

Headings

  • Headings should use Title Capitalization Like This.
  • Subheadings, anything less than h1 or markdown level 1: #, should use Sentence capitalization like this.
  • Subheadings which are numbered steps to follow should start with Step 0:.
  • Subheadings which are numbered steps should have the first word after the colon capitalized like this: Step 0: Do something great.
  • Headings should not end with a period.
  • Leave a blank line above and below headings.
  • Use the infinitive verb form in all types of headings (correct: "Try out Hasura permissions", wrong: "Trying out Hasura permissions").
  • Add an introduction section as ## Introduction with a short overview of what the page is about.
  • Page titles should be self-sufficient. Users might not have the context of the hierarchy of the page in the docs tree. A user can land on a page via search as well. e.g. Say you are adding a new deployment guide for AWS under Guides -> Deployment -> AWS. The title of this page should not be just AWS but instead AWS deployment guide for Hasura GraphQL Engine. It's ok to alias it to just AWS in the sidebar (sidebar_label: AWS) as there the user has the context of the page hierarchy.