Skip to content

Latest commit

 

History

History
150 lines (100 loc) · 6.3 KB

.CONTRIBUTING.md

File metadata and controls

150 lines (100 loc) · 6.3 KB
Raw

Contribution Guidelines

The documentation source files are written in Markdown and generally follow the Google developer documentation style guide.

Please review the guidelines mentioned throughout this document, and when ready, you can open a PR against the main branch. Typically from there, someone from the Tanssi Developer Relations team will review the PR and request any changes as needed. Then the team will merge your PR into a local branch and make sure that all of the formatting changes look good on the local site. Once everything is all set and done the changes will be published to the live site.

Thank you for your contributions, they are greatly appreciated 💜.

Previewing Changes

To preview your changes, you can follow these steps:

  1. Fork and clone the tanssi-mkdocs repo

  2. Add your clone of the tanssi-docs repo inside the root directory of tanssi-mkdocs

  3. Run the following command to install dependencies:

    pip install -r requirements.txt

  4. Then run mkdocs serve, which will build and serve the docs site on port 8000

Previewing Changes in VS Code

If you're using Visual Studio Code, you can preview the changes you're making to .md files before committing them. To learn how, please check out the Markdown and Visual Studio Code guide from the Visual Studio docs site.

Structure

In the root directory and every subdirectory, in addition to the content directories and pages, you'll find the following files:

  • .pages - defines the structure of the documentation site
  • index.md- represents the landing pages you see throughout the docs site

Example .pages file

Below is an example of a .pages file:

title: Builders
hide: false
nav:
  - index.md
  - build
  - deploy
  - interact
  - technicals

Some important things to note:

  • The title field at the top of the page represents the display name for the subdirectory
  • The index.md page should always be the first item in the list
  • Files follow the convention of 'Display Name': 'file-name.md'
  • Subdirectories are listed by their directory name in the source code

Example index.md file

Below is an example of an index.md file:

---
title: Build your Appchain
description: Install the software to compile yousr appchain, configure your genesis state and core functionalities, test locally and get ready to deploy through Tanssi.
template: subsection-index-page.html
hide:
 - toc
 - feedback
---

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
  • The template defines the template to be used. It should always be main.html for new content pages and subsection-index-page.html when adding a new section
  • The <div> is populated with links to any pages or subdirectories and is populated automatically by a script at runtime that builds the landing pages

Content Pages

When adding a new content page, you should have the following components:

  • title - represents the <title> tag and is used for SEO purposes (not displayed on the published site)
  • description - represents the meta-description and is also used for SEO purposes (not displayed on the published site)
  • Page title - a title to be displayed at the top of the page
  • ## Introduction section - 2-3 paragraphs to serve as an introduction. This should be long-lived, meaning it will not require changes in the future

Optionally, you should also consider including the following sections:

  • ## Checking Prerequisites section - if the guide requires the user to have certain developer tools installed, for example, Docker or MetaMask, it should be listed here
  • ## Getting Started section - if this is a 3rd party integration, having links that point to the most important parts of your project's documentation site that helps users get started with your project

For example:

---
title: Title for SEO purposes
description: Description for SEO purposes.
---

# Page Title

## Introduction

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

...

Images and Icons

Images are stored in the images subdirectory. They are organized to mirror the structure of the docs site. So, for example, if you are creating a new page for the builders section and need to add images, those would go under the images/builders/ subdirectory.

All landing pages require a logo or relevant icon. You can use the _index-page-icon-template.svg that is in the root of the images subdirectory to create your own that is the correct size. Images should follow these specs:

  • Have a transparent background
  • Be 256x256px in size
  • Be added in .webp format
  • When exporting the SVG to a PNG, please use a DPI of 300
  • The colors should be:
    • Light mode: #262626
    • Dark mode: #e9e9e9

These images are stored in the images/index-pages subdirectory.

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

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

Snippets

Snippets can be used to manage reusable lines of code or text. There is a subdirectory for text and code.

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

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

Code snippets can be written in Markdown or the programming language itself, for example, .py for Python, .js for JavaScript, etc.

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 110 and 160 characters.