Skip to content

Latest commit

 

History

History
62 lines (39 loc) · 3.25 KB

CONTRIBUTING.md

File metadata and controls

62 lines (39 loc) · 3.25 KB
Raw

Thank you for your interest in contributing to the Insomnia Docs.

Site overview and markdown styling

The Insomnia documentation site is built using Jekyll, a static site generator and Bootstrap 5. When updating content, navigate to:

  • the inso-cli directory for Inso CLI documentation pages
  • the insomnia directory for Insomnia (client) documentation pages

Use Markdown instead of HTML

Stick to Markdown as much as possible in Markdown files. Use the following classes to style elements:

Element Markdown class
table {:.table .table-striped}
note callout {:.alert .alert-primary}

Accessibility

The Insomnia documentation site aims to follow AAA WCAG accessibility standards.

Since we use Bootstrap 5 and it tends to be accessibility-friendly, use their HTML where you need accessible elements and you cannot easily create them with Markdown.

See Install Inso CLI for an example of accessible tabs. Note that in this case, we opted to add HTML into the Markdown file.

Add a new page

Add a new page if you are adding documentation for a new topic. Don't add a new page for FAQ-type content. Take time to see where the content fits in.

  • Add the file to either the inso-cli or insomnia folder.
  • Name the file descriptively and use full words where possible.
  • Add the page title and local url to _data > main-nav.yaml under the corresponding section.

Keep it simple

  • Don't add unnecessary and excessive packages.
  • Use screenshots very sparingly. And if you add a screenshot, ensure it has descriptive alt text and a short description underneath. See Introduction to Insomnia for an example.
  • Use the Oxford Comma to prevent any misinterpretation.
  • Use Vanilla JS where needed. No need to add jQuery.
  • For icons, use Google Icons. This means we don't have to download an entire library to use just a few icons.

Contributing resources

Insomnia is a Kong product, and we follow the same Contributing Guidelines and Style Guide. Here's more information about becoming an effective contributor.

Capitalization

Capitalize the following words, as they refer to entities in our client:

  • Project
  • Collection
  • Document
  • Commit

Contributor T-shirt

If your pull request to Kong/insomnia-docs was accepted, and it fixes a bug, adds functionality, or makes it significantly easier to use or understand Insomnia, congratulations! You are eligible to receive the very special contributor t-shirt! Go ahead and fill out the contributor submission form.