Skip to main content

Genesis Developer Docs

Contribute to Genesis Docs

Thank you for your interest in contributing to Genesis developer documentation.

If you need help with a theme or plugin customization, please use the community resources.

If you would like to report a correction or make a request for more developer documentation, please submit your comments to our support team or in the GenesisWP Slack workspace.

If you would like to edit or add new developer documentation yourself, read on!

About the Genesis documentation site #

This site is built from Markdown files and templates in the main Genesis repository using the Eleventy static site generator. Documentation for Eleventy is available here: https://www.11ty.io/docs/.

Genesis includes tooling to help you build this site locally, open it in a browser, make changes to documentation files, and see those changes reflected immediately before you contribute your new documentation back to Genesis.

You will need #

  1. Familiarity with the git version control system and GitHub code hosting service. The git handbook from GitHub and this free git course from Tower are good places to start if you're new to git.
  2. Access to the private Genesis GitHub repository, where Genesis developer documentation lives.
  3. Node.js installed on your computer. The “Node.js package manager” (npm) comes with Node.js. npm is what we use to “build” the documentation website from the documentation files.
  4. Basic command line knowledge. You will need to open a command prompt on your computer, change directories with cd, and type the commands below to run the documentation development server.

If you get stuck with these requirements or the steps below, feel free to post in the contributors channel in the GenesisWP Slack workspace.

Getting started #

Once you have Genesis repository access, Node.js, and a git command line or graphical client installed, you can:

  1. Visit the Genesis repository and fork it. This creates a copy of Genesis under your own GitHub account. Forking lets you experiment, make changes, and contribute those changes without worrying about breaking the main Genesis repository or obtaining permissions to modify it directly.
  2. Clone your fork of the Genesis repository. Cloning creates a local copy of your forked repository on your own computer so that you can edit it.
  3. Open a command line application, and change directory to your local Genesis directory. (On macOS, open the Terminal app, type cd followed by a space, drag the genesis folder onto your terminal window to get the full path, then press enter.)
  4. Type npm install and press enter to install dependencies needed to build the documentation.
  5. Type npm run docs:css to build the initial CSS from the Sass files.
  6. Type npm run docs:dev to build the documentation site. This also starts a server on your machine to preview and work on docs.
  7. In your web browser, visit http://localhost:8080 (or the URL you see in your command line application after running docs:dev).

You should see the documentation site. It will automatically refresh with changes you make to documentation content and styling. To stop the server, focus the terminal window you launched the development server with and press Ctrl + c. (You may see some errors from npm when the server closes, but these are safe to ignore.)

Making changes #

It's best to first create a local git branch to work in. This keeps your changes separate to the main develop branch where Genesis development occurs, and makes it easier for reviewers to see what you're proposing to alter.

If you intend to make extensive changes that are not just copy edits or styling tweaks, we recommend that you first open an issue in the Genesis repository with a proposal.

To edit existing documentation #

Existing documentation lives in the genesis/docs folder as Markdown files with the .md extension. Documentation files are named with numerical prefixes to match their position in the menu, using the following convention:

1-00-intro.md             → Top-level item, no children.
2-00-basics.md            → Top-level item, parent of 2-01.
2-01-how-genesis-works.md → Child of 2-00-basics.md.

You can edit these files directly, and you'll see your changes reflected straight away if the development server is still running.

If you're unsure about where a specific page's Markdown file is located, view the source of the page and look for the comment near the end:

<!-- To change this content, edit ./docs/3-00-features.md -->

To edit the changelog #

The changelog page is built automatically from the contents of the genesis/docs/changelog directory. Edit the individual file in that folder corresponding to the Genesis version you'd like to alter.

To add new pages #

Add a new page at the relevant level in the menu by following the above naming convention.

New Markdown files must begin with a header containing meta data like this:

---
title: Contribute to Genesis Docs
menuTitle: Genesis Docs
layout: layouts/base.njk
permalink: contribute/genesis-docs/index.html
tags: docs
---

All documentation must include the docs tag, and you should update the permalink depending on what URL you want the finished document to appear at, and the title and menuTitle to reflect the document page h1 and its name in the menu.

To specify that a feature requires a version of WordPress or Genesis, use the minVersion meta in the Markdown file heading:

---
[rest of header removed]
minVersion: Genesis 2.7.0+
---

Or:

---
[rest of header removed]
minVersion: Genesis 2.7.0+ and WordPress 4.9.6+
---

To remove pages #

If you remove a page, you will need to stop the development server and perform the following actions before you see your changes reflected:

  1. Type npm run docs:clean to remove the genesis/docs/_site folder where documentation is built and served from.
  2. Type npm run docs:css to build the initial CSS.
  3. Type npm run docs:dev to build the documentation and start the development server again.

Formatting links and other content #

To add images #

  1. Compress your image using a service such as TinyPNG.
  2. Copy your image to the genesis/docs/img directory.
  3. Reference your image in the documentation using this syntax:
<img src="{{ '/img/your-filename.png' | url }}" alt="">

Complete the alt tag attribute if the image adds important information a partially sighted visitor would benefit from, otherwise leave the alt attribute contents blank. Do not remove the alt attribute.

You must use the following format for links to other Genesis documentation pages:

<a href="{{ '/page' | url }}">the page</a>

Passing root-relative URLs through the Eleventy url filter in this way ensures that internal links gain an additional '/genesis/' prefix when the site is built for hosting on GitHub Pages at https://studiopress.github.io/genesis/, while continuing to work when you run the local development server (which doesn't have the /genesis/ prefix).

Note that every heading in documentation pages gets its own ID attribute, so you can link directly to headings with a fragment identifier:

<a href="{{ '/page/#the-title' | url }}">the title</a>

Markdown files are pre-processed with the Liquid templating system, so you can use other Liquid tags too.

External links can use the Markdown format:

[WP Engine](https://wpengine.com/)

Or regular HTML:

<a href="https://wpengine.com/">WP Engine</a>

Notices #

There are three notice paragraph styles you can use:

<p class="notice">
A regular notice with the <code>notice</code> class.
</p>

<p class="notice-big">
A bigger notice with the <code>notice-big</code> class.
</p>

<p class="notice-small">
A small notice with the <code>notice-small</code> class.
</p>

Which produces this styling:

A regular notice with the notice class.

A bigger notice with the notice-big class.

A small notice with the notice-small class.

Note that notices must use HTML inside. Markdown will not be processed.

Buttons #

Buttons are styled as plain HTML links with a button class:

<a href="https://www.studiopress.com/" class="button">Visit StudioPress</a>

Resulting in this:

Visit StudioPress

Source code #

Wrap source code blocks with three backticks and the language name, like this for PHP:

```php
/**
 * PHP code
 *
 * This is a comment.
 * It spans multiple lines.
 */
function php_test( $test ) {
    var_dump( $test );
}
```

And this for JavaScript:

```js
function jsTest(test) {
    console.log('This is a test.');
}
```

Which results in this:

/**
 * PHP code
 *
 * This is a comment.
 * It spans multiple lines.
 */
function php_test( $test ) {
    var_dump( $test );
}
function jsTest(test) {
    console.log('This is a test.');
}

Code on a single line or within a sentence should be wrapped in single backticks:

The `var_dump()` function is not a replacement for Xdebug.

Which produces:

The var_dump() function is not a replacement for Xdebug.

Code syntax highlighting is prerendered by Eleventy during documentation builds for performance, instead of depending on JavaScript in the visitor's browser.

Keyboard shortcuts #

Wrap keyboard characters with <kbd> to style them as keys:

<kbd>Ctrl</kbd> + <kbd>c</kbd>

Which produces this:

Ctrl + c

Editing HTML templates #

Templates are located in these _includes directories, with an .njk extension:

Templates use the Nunjucks JavaScript templating engine, and Eleventy includes templating documentation here.

Editing styling #

Find styling at docs/sass. This is automatically minified and built as docs/css/style.css. CSS source maps are generated for the development server to help you inspect elements and see which Sass file is responsible for styling.

Contribute your changes #

To contribute your documentation changes back to Genesis:

  1. Commit your changes in the branch you created.
  2. Push the changes to your fork of Genesis.
  3. Open a pull request in the main Genesis repository. This is a way of asking that your changes be merged into Genesis itself.

Building Genesis docs for production #

These steps are included for completeness. You will not need to do this unless you intend to host Genesis documentation.

First, stop the documentation development server if it's running. Then:

  1. From the Genesis directory, type npm install to install dependencies if you have not done this already.
  2. Type npm run docs to build docs in the genesis/docs/_site directory.
  3. Copy the contents of the genesis/docs/_site directory to the root of your server, or to the gh-pages branch of your repository if using GitHub Pages.

If docs will not be hosted in a /genesis/ subdirectory such as https://studiopress.github.io/genesis/, you will need to alter or remove the --pathprefix= flag in the docs:eleventy script in genesis/package.json.