Documentation

The documentation for the PWABuilder repository lives in the docs sub-directory, and can be found at docs.pwabuilder.com.

Contributing to the Documentation

Contributing to the docs is easy:

1. Open an issue on the PWA Builder issue board.

2. Fork the pwa-docs repository to your personal GitHub account.

3. Create a branch off main for your changes. Use the issue number and a descriptive branch name. For example, if I'm addressing Issue #1234, I would call my branch 1234-fix-quickstart-typos

4. Make your changes. See the writing guidelines below for more details on style conventions.

5. Run the docs locally to double-check your changes. More information on working with Docsify is included below.

6. Open a Pull Request into the pwa-builder/pwa-docs repository.

7. Wait for your changes to be reviewed. Someone may request changes or merge or your changes!

Writing Guidelines

Make sure any new or edited documentation follows these guidelines:

General Guidelines

• Write clear, simple sentences that get the point across.

• Double-check for grammar, punctuation, and spelling.

• Break up long text blocks with line breaks, images, or code snippets.

Links

• If you reference somewhere else in the documentation, link to it.

• If your article needs context and the information already exists in the documentation, feel free to use a link.

• When referencing outside materials, prioritize official Microsoft Docs or MDN resources.

Headers

• Use a single H1 header (#) at the top of your article for the title.

• For any subsections that you want included on the sidebar, use a H2 header (##). Docsify will automatically include H2 headers on the sidebar.

• If you want to header a section that you don't want included on the sidebar use a H3 header (###) or smaller. Docsify is configured to not include H3 or smaller.

• Keep your headers short and descriptive and organize your sections in a logical order.

Images

• Place all images in the assets subdirectory specific to that article. If you are creating a new article, create a new directory for that article.

• Keep images a reasonable size and keep smaller displays in mind. Set widths for your images with html.

• Provide alt text for all images.

• Place all images in <div> tags with a class of docs-image to enable global image styling.

For example:

<div class="docs-image">
    <img src="..." width=500 alt="...">
</div>

Code Snippets

• Use code snippets when you can! The documentation has a copy code plugin that makes it easy for readers to use snippets. They also break up text and make the documentation more practical.

• Make sure to add context to any snippets - don't expect the reader to fully understand standalone code.

Lists

• If your list is a step-by-step, use a numerical list.

• If your list is related items, but not a step-by-step, use a bulleted list.

• Add a line break in between list items to format them with a bit more breathing room.

Working with Docsify

PWABuilder docs are built with Docsify! Here are some quick tips for working with Docsify.

Installing the CLI

In order to run the docs locally, you can install the docsify-cli with NPM:

npm i docsify-cli -g

Running the Docs Locally

Once you have the CLI installed, you can run the docs locally by running:

docsify serve docs

Where docs is the docs directory at the root of pwa-docs.

Adding New Pages

Docsify automatically iterates through subdirectories to add any .md files to the docs. To add a page, create a new Markdown file in the proper subdirectory for whichever tool you are adding documentation for. If you add a PWA Starter page, it could be found at localhost:3000/#/starter/new-page.

Once you have your file created, you can add it to the sidebar by editing _sidebar.md in the docs directory.

Editing Styling

All of the custom styling is done through docsify-themeable, which exposes custom CSS properties to edit the appearance of the docs. All properties can be found in the global.css file.