pages/site/publishing-gerrit-docs.md

title: “Publishing Gerrit Documentation” sidebar: gerritdoc_sidebar permalink: publishing.html hide_sidebar: true hide_navtoggle: true toc: true

This topic describes how to publish updates to the Gerrit website.

Prerequisites

Install Docker
Install Docker Compose
Prepare your system to host content on Firebase.
Have the appropriate permissions to the Gerrit Code Review project on the Google Cloud Platform.

Cloning the repository

The repository that contains the Gerrit website is called homepage.

To clone the repository, run the following command.

git clone https://gerrit.googlesource.com/homepage && \
(cd homepage && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg \
https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; \
chmod +x `git rev-parse --git-dir`/hooks/commit-msg)

Building the site

In these steps, you build the site on your local machine.

The output files for the site are stored in the _site directory. This directory is not stored in the repository.

To build the site:

Navigate to the root of the homepage repository.
Type the following command:
```
docker-compose up
```

The docker file is configured to build the site and serve it on a local staging server. To access the staging server, navigate to the following URL in your browser:

http://localhost:4000

To build the site without staging it, type the following command:

docker run -v $(pwd):/site bretfisher/jekyll-serve jekyll build

Deploying the site

Note: If this is your first time running Firebase on this machine, you need to provide authentication credentials. For more information, see Appendix: Logging in to Firebase.

To deploy the site:

Make sure you have proper ownership of the output files.

sudo chown -R $( id -u $USER ):$( id -g $USER ) _site/

Type the following command from the root of the repository:
```
firebase deploy
```

In a few moments, the site is updated. You can view the deployment in the Firebase console.

Rolling back to another deployment

Open the Firebase console.
From the left navigation pane, click Hosting.
In Deployment History, select the deployment you'd like to return to.
Click the More button (three vertical dots).
Select Rollback.

Writing content

This section describes how to add new content to the documentation.

Note: For complete documentation on the site template and how to create content, see Getting started with the Documentation Theme for Jekyll.

Using the text editor of your choice, create an empty document.
At the top of the document, add the following text block:
```
---
title: [TITLE_NAME]
sidebar: [SIDEBAR_NAME]
permalink: [FILENAME]
---
```
Where:
- TITLE_NAME is the title of the topic.
- SIDEBAR_NAME is one of the following values:
  - gerritsidebar: This sidebar is used for most topics.
  - errors_sidebar: This sidebar is used for error messages.
  - cmd_sidebar: This sidebar is used for the command reference topics.
  - restapi_sidebar: This sidebar is used for the REST API reference.
  - userguide_sidebar: This sidebar is used for the Gerrit User Guide (currently in alpha
- FILENAME is the output name of the file. This name MUST be unique.
Author your topic using the Kramdown Markdown.

Save the file in the following directory:

path/to/repository/jekyll-source/pages/gerrit

This template supports a few additional extensions for authoring content. Some that you might find useful include:

For more information on how the documentation is structured and the syntax it supports, see the template documentation.

Writing blog posts

The Gerrit website supports adding blog posts. Users can view a list of current blogposts by click the News link in the navigation bar.

To create a blog post:

Create a new markdown file. The name of the file must use this format:
```
YYYY-MM-DD-[permalink].md
```
Where [permalink] is a descriptive name of the file.
Add the following to the top of the blog post:
```
---
title: [TITLE]
tags: [TAGS]
keywords: [KEYWORDS]
permalink: [FILENAME].html
summary: [SUMMARY]
hide_sidebar: true
hide_navtoggle: true
toc: true
---
```
Where:
- [TITLE] is the title of the blog post
- [TAGS] is an optional comma-delimited list of tags
- [KEYWORDS] is an optional comma-delimited list of keywords
- [FILENAME] is the name of the file
- [SUMMARY] is a one- to two- sentence description of the post
Save the new post in the _posts directory.
Save any images in the top-level images directory.

Appendix: Logging in to Firebase

If you have never used Firebase before, you need to perform these steps:

Install the Firebase CLI.
Log in to Firebase.
Note: After you provide your credentials, you are returned to http://localhost to confirm your authentication. If you cannot access localhost for some reason, you can run this command instead: firebase login --no-localhost.
Initialize Firebase.
Note: When you initialize Firebase, specify _site as the root directory. Accept the defaults for all other options.

Appendix: Jekyll Template

Jekyll sites use a variety of templates. For Gerrit, we have selected this template. We chose this template because it has robust support for documentation. For example, this template supports:

A left navigation system that includes sections that can expand and collapse
Support for tabs within content, which makes it easier to display multiple options for users (for instance, displaying GWT or PolyGerrit instructions)
A simple, but extensible Search box

As the theme is already included in the repository for the Gerrit site, you should not need to install it when making changes to your content. However, to learn about the template and its features, use the following link:

http://idratherbewriting.com/documentation-theme-jekyll/