Skip to content

Latest commit

 

History

History
210 lines (136 loc) · 10.1 KB

.CONTRIBUTING.md

File metadata and controls

210 lines (136 loc) · 10.1 KB
Raw

Contribution Guidelines

The documentation source files are written in Markdown and generally follow the PaperMoon style guide. If the PaperMoon style guide does not provide explicit guidance on a particular subject, please default to the Google developer documentation style guide.

This guide covers how to contribute to the documentation, including serving a local version of the site, adding new pages and directories, managing images and code snippets, and a few SEO tips.

Contents

Viewing Site Locally

You may want to spin up a local version of the documentation site to preview your changes. This guide will cover the steps needed to serve a local version.

Clone Repositories

Building and serving the site requires cloning two repositories:

  • Wormhole MkDocs - contains the MkDocs config files, theme overrides, and custom CSS for the Wormhole documentation site

  • Wormhole Docs - the actual content is stored in the wormhole-docs repo and pulled into the wormhole-docs directory during build

For everything to work correctly, the file structure needs to be as follows:

wormhole-mkdocs
|--- /material-overrides/ (folder)
|--- /wormhole-docs/ (repository)
|--- mkdocs.yml

To set up the structure, follow these steps:

  1. Clone this repository:

    git clone https://github.com/papermoonio/wormhole-mkdocs

  2. Inside the folder just created, clone the wormhole-docs repository:

    cd wormhole-mkdocs
git clone https://github.com/wormhole-foundation/wormhole-docs.git

Install Dependencies and Serve Site

  1. Now that the repositories are cloned and properly nested, use the pip package installer to install mkdocs and other required dependencies by running the command:

    pip install -r requirements.txt

    This command will install all dependencies listed in the requirements.txt file.

  2. In the wormhole-mkdocs folder (which should be the current one), you can build the site by running:

    mkdocs serve

After a successful build, the site should be available at http://127.0.0.1:8000.

Adding New Pages

When adding new pages to the documentation site, it is important to ensure all relevant items are updated correctly to prevent broken links and unexpected behavior. This section guides you through the steps to add new documentation pages.

Creating a New Section

To create a new section of pages, you will first need to create a subdirectory with the desired name of the section. The root directory, and every subdirectory, must contain the following files:

  • .pages - defines the structure of the documentation site
  • index.md - a landing page which can be used to provide more context about the content in the section

Example .pages File

title: Build Apps
nav: 
  - index.md
  - 'Wormhole SDK': 'wormhole-sdk.md'
  - queries
  - connect

This example would result in adding 'Build Apps' as a section with two files inside, index.md and wormhole-sdk.md, and two additional subdirectories named queries and connect.

Some important things to note:

  • The title field at the top of the page represents the display name for the section. This is displayed on the left-side navigation bar when viewing the site
  • The index.md page should always be the first item in the nav list
  • Files follow the convention of 'Display Name': 'file-name.md'
  • Sections are listed by their directory name in the source code. For example, the Queries section will be added to the navigation simply by using the directory name: queries

Example index.md File

---
title: Build DApps with Wormhole
description: Learn how to use the Wormhole SDK, queries, and Wormhole Connect to build DApps with seamless cross-chain message transfer capabilities.
---

<!-- Add content in markdown here -->

Some important things to note:

  • The title represents the <title> tag and is used for SEO purposes
  • The description represents the meta-description and is also used for SEO purposes

Adding Pages to Existing Section

If you are adding pages to an existing section, the steps are simplified. However, it's essential to ensure you complete these steps to display the new page and its title on the documentation site correctly:

  • Add the new markdown page to the appropriate section. Note that the filename becomes part of the URL for this page. See the style guide for additional guidance on naming conventions.

  • Ensure the new content page includes the following:

    • title - represents the <title> tag and is used for SEO purposes (not displayed on the published site) Titles have a maximum length of 45 characters.

    • description - represents the meta-description and is also used for SEO purposes (not displayed on the published site). Descriptions should be between 120-160 characters and should provide a preview into the page topic.

    • Page title - an H1 heading title to be displayed at the top of the page

    • ## Checking Prerequisites section - if the guide requires the user to have specific developer tools installed, for example, Docker or MetaMask, it should be listed here

  • Add the 'Display Name': 'file-name.md' for the new page to the .pages folder in the same subdirectory where you added the new page

An example new content page might look like:

---
title: Title for SEO purposes 
description: Description for SEO purposes. This should be a sentence or two that is between 120-160 characters long.
---

# Page Title

## Introduction

Write 2-3 paragraphs to serve as the introduction here.

...

More resources for SEO Optimization of titles and descriptions.

Modifying Existing Pages

To modify existing pages:

  1. Ensure you are in the wormhole-docs directory, then create a new branch for your content:

    git checkout -b INSERT_NEW_BRANCH_NAME

  2. Modify content as desired. Remember to place images and code snippets in the appropriate folders (see the following sections for details)

  3. Review the style guide to ensure your new content meets the guidelines

  4. Once you commit and pushed all of your changes, open a pull request for the new content branch against the main branch

  5. Monitor notifications and pull requests for feedback from code owners. At least one approval is required before merging content

If your additions or modifications are limited to content on an existing page, there is no need to worry about the .pages or index.md files, as changes to page content do not affect these files.

Adding Code and Text Snippets

Snippets are used to manage reusable lines of code or text. They are organized to mirror the structure of the docs site and stored under the root-level .snippets directory. For example, to add a code snippet to the page build/applications/wormhole-sdk.md, you would place the code snippet in the folder .snippets/code/build/applications/wormhole-sdk.

Text snippets are useful for pieces of copy you find the need to reuse often, such as disclaimers. Code snippets allow you to reuse pieces of code throughout a document while maintaining a single place to update that code when needed.

To link to a snippet, you can use the following syntax in the Markdown file:

--8<-- 'code/<subdirectory>/<snippet-file-name>.js'

Text snippets are written in Markdown, as .md files, while code snippets should be written in their individual programming languages, for example, .py for Python or .js for JavaScript.

Learn more about the effective use of snippets.

Adding Images

Images are stored in the images subdirectory. They are organized to mirror the structure of the docs site. For example, to add an image to the page build/applications/wormhole-sdk.md, you would place the image in the folder images/build/applications/wormhole-sdk.

All images intended for display on the website should be in .webp format. You can look up an image converter online to convert from .jpeg, .png, or other formats to .webp.

To add an image to your page, you should have alt text and use the following syntax:

![Alt text goes here](/docs/images/<subdirectory>/<image-file-name>.webp)

See the style guide for more tips on handling images.

Search Engine Optimization (SEO)

Here are some resources to help you create good titles and descriptions for SEO:

In general, titles should be between 50 and 60 characters and descriptions should be between 120 and 160 characters.