Hello! Thank you for choosing to help contribute to one of the SendGrid open source libraries. There are many ways you can contribute and help is always welcome. We simply ask that you follow the following contribution policies.

All third party contributors acknowledge that any contributions they provide will be made under the same open source license that the open source project is provided under.

• Content Request
• Improvements to the Codebase
• Local Setup
  • Dependencies
  • Setup Steps
  • Configure Jekyll
  • Running
  • View Your Install
• Config
  • Pages
    • SEO
  • Custom Liquid Tags
    • Anchors
    • Info blocks
    • API Examples
• JS and CSS, etc.
• Creating a Pull Request

Feel free to grab an issue you want to work on. Please indicate that you have begun work on it to avoid collisions. Once a PR is made, community review, comments, suggestions, and additional PRs are welcomed and encouraged.

Submit all pull requests to the develop branch.

There are a few ways to contribute, which we'll enumerate below:

If you'd like to make a content request, please read this section.

The GitHub issue tracker is the preferred channel for docs content requests, but please respect the following restrictions:

• Please search for existing issues in order to ensure we don't have duplicate bugs/content requests.
• Please be respectful and considerate of others when commenting on issues.

We welcome direct contributions to the SendGrid docs code base. Thank you!

• Required:
  • Git
  • Rvm
  • Homebrew
  • npm
  • Gatsby

• Install Git for:

  • Mac
  • Windows
  • Linux

• Install RVM

  $ \curl -sSL https://get.rvm.io | bash -s stable --ruby

• Install Homebrew (if you don't have it)

  $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

• Install npm

  $ brew install npm

Note: You may need to use 'sudo' before the command to get it to work as intended.

• Set your Node version

  $ npm install -g n

  $ n 8.4.0

• clone repo

  $ git clone https://github.com/sendgrid/docs.git

• Go to your docs directory

  $ cd docs

• switch to develop branch to make changes

  $ git checkout develop

• Install Gatsby

  npm ci

• Build the local site

  gatsby develop Gatsby starts a hot-reloading development environment accessible at localhost:8000

The gatsby config is defined in gatsby-config.js. The site config is defined in data/SiteConfig.js which you usually don't have to modify but are helpful to know about.

You can write pages in markdown, HTML, or HAML. They all get converted to HTML when the site is generated.

Pages have a block of YAML at the top that sets a few options. They are pretty self-explanatory; here's an example

---
layout: page
weight: 0
title: Docs Home
icon: icon-home
showTitle: false
navigation:
  show: true
---

Weights are same as the folder weights - the higher numbers move higher up the tree. Icons are based on the CSS icon class names from Twitter Bootstrap. showTitle and navigation["show"] both default to true if not specified.

Various fields pertinent to SEO can be controlled through the YAML front matter. Here's an example:

---
seo:
  title: Really Great Documentation - SendGrid Documentation | SendGrid
  override: true
  description: This is some really great documentation! I hope you like it!
  canonical: https://sendgrid.com/docs/really-great-docs
---

By default <title> tags follow the template {Page Title} {Site Title}. However the page title can be changed for the purpose of the tag by using seo["title"]. seo["override"] will override the entire template, instead making the title page {seo["title"]}. description and canonical change their respective tags.

There are some custom plugins (look in the plugins folder) that define new liquid blocks for use in pages.

You can create anchor tags that will have named anchors generated for them automatically with links on hover. The parameter is the wrapping element to use.

{% anchor h2 %}
Some Anchor Text
{% endanchor %}

Similarly you can create info and warning blocks:

{% info %}
Some info for a breakout block.
{% endinfo %}

{% warning %}
...And a warning breakout.
{% endwarning %}

If you are working on API reference docs, you can generate XML and JSON nav tabs and the corresponding example calls and responses like so:

{% apiexample identifier GET http://some.endpoint.url var1=stuff&var2=junk %}
  {% response json %}
{ "foo": "bar" }
  {% endresponse %}

  {% response xml %}
<foo>bar</foo>
  {% endresponse %}
{% endapiexample %}

The parameters for the apiexample block are: unique identifier, HTTP method, the url (excluding .json or .xml extension), and the data payload in querystring format.

JavaScript and CSS are minified and combined. The files to be packaged and their orders are specified in _includes/head.html and CssMinify.yml. Preprocessing and options can be specified via _plugins/jekyll_asset_pipeline.rb.

1. Fork the project, clone your fork, and configure the remotes:

   # Clone your fork of the repo into the current directory
   $ git clone https://github.com/sendgrid/docs
   # Navigate to the newly cloned directory
   $ cd docs
   # Assign the original repo to a remote called "upstream"
   $ git remote add upstream https://github.com/sendgrid/docs

2. If you cloned a while ago, get the latest changes from upstream:

   $ git checkout <dev-branch>
   $ git pull upstream <dev-branch>

3. Create a new topic branch (off the main project development branch) to contain your feature, change, or fix:

   $ git checkout -b <topic-branch-name>

4. Commit your changes in logical chunks. Please adhere to these git commit message guidelines or your code is unlikely to be merged into the main project. Use Git's rebase feature to tidy up your commits before making them public.

   4a. Create tests.

   4b. Create or update the example code that demonstrates the functionality of this change to the code.

5. Locally merge (or rebase) the upstream development branch into your topic branch:

   $ git pull [--rebase] upstream master

6. Push your topic branch up to your fork:

   $ git push origin <topic-branch-name>

7. Open a Pull Request with a clear title and description against the develop branch. All tests must be passing before we will review the PR.

If you have any additional questions, please feel free to email us or create an issue in this repo.