This document describes the options available for creating content for the site, along with some guidelines and conventions. We are thankful to you for thinking about contributing to our doc set!
This site is built using propeitary documentation tooling that uses Markdown as it's authoring language. Learn more about Markdown:
The following sections provide information about different elements of a page. Use these as guidelines when you start authoring or editing a document.
To ensure that each page can be correctly identified, we use the frontmatter. At the top of each docs page, include the following elements:
||A brief string that uniquely identifies the page within its parent folder.|
||The main title of the page.|
||This is what will appear in the left hand navigation tree for the page.|
||This is what appears when the page is referenced in a Google search result.|
When you are done, the document would look as follows:
--- id: overview-contributing title: Overview sidebar_label: Overview description: Nightwatch Contribution Guidelines ---
The first paragraph of the documentation is a window to setting expectation in terms of what the content on the page woudl help the user accomplish. As a guidelines, describe the benefits of the feature followed by an example of where they can use it.
Apart from the standard markdown guidelines of heirarchical headers, for example, H2 must be nested under H1, H3 must be nested under H2, etc., use the following guidelines:
- H2 header is used as title that appears as page header and on the left navigation pane. Use the
<div class="page-header"><h2>Adding custom assertions</h2></div>format to differentiate a H2 header that will be used as the page title.
- H2 header is used for SEO, so ensure that it is crafted concisely.
- Each page includes only one H2 header.
- H3 headers are included in the page's table of contents on the right. Use H3 headers to add actionable content. All H3 headers are underlined by default.
- H4 headers can be created using custom format
<div class="page-header"><h2>Adding custom assertions</h2></div>
Staying true to the nature of Markdown, all content is rendered as a single paragraph. When you add an empty line, a new paragraph begins. As such, it is good practice for each line to be less than 120 characters long for readability, when possible.
[Yet to write]
To refer to a single class or method name within a sentence, place single backticks around the name.
This comment refers to the
When you have code blocks, use the following format. Markdown highlights each language differently, so it is helpful to specify which language you are using, and it's a good idea to include a title with the code block as well.
your code goes here
There are two types of admonitions:
- info - Relevant information.
- Warning - A user might do something dangerous!
The below commands runs an example test which opens the search engine Ecosia.org, types the term "nightwatch" into the search input field, then verifies if the results page contains the text "Nightwatch.js".
To improve support for displaying the output when running tests in parallel, we recommend setting
Use the tables generator to generate markdown tables and use as is.
List are used either to represent steps that must be followed in a particular order or list of prerequisites that must be adhered to:
Linking to another page
Use the markdown syntax for linking to another page:
|Display||External: Creating and publishing unscoped public packages|