[id="contributing-to-docs-tools-and-setup"]
= Install and set up the tools and software

:icons:
:toc: macro
:toc-title:
:toclevels: 1
:linkattrs:
:description: How to set up and install the tools to contribute

toc::[]

== Create a GitHub account
Before you can contribute to OpenShift documentation, you must
https://www.github.com/join[sign up for a GitHub account].

== Set up authentication
When you have your account set up, follow the instructions to
https://help.github.com/articles/generating-ssh-keys/[generate and set up SSH
keys on GitHub] for proper authentication between your workstation and GitHub.

Confirm authentication is working correctly with the following command:

----
$ ssh -T git@github.com
----

== Fork and clone the OpenShift documentation repository
You must fork and set up the OpenShift documentation repository on your
workstation so that you can create PRs and contribute. These steps must only
be performed during initial setup.

. Fork the https://github.com/openshift/openshift-docs repository into your
GitHub account from the GitHub UI. You can do this by clicking on *Fork* in the
upper right-hand corner.

. In the terminal on your workstation, change into the directory where you want
to clone the forked repository.

.  Clone the forked repository onto your workstation with the following
command, replacing _<user_name>_ with your actual GitHub username.
+
----
$ git clone git@github.com:<user_name>/openshift-docs.git
----

. Change into the directory for the local repository you just cloned.
+
----
$ cd openshift-docs
----

. Add an upstream pointer back to the OpenShift's remote repository, in this
case _openshift-docs_.
+
----
$ git remote add upstream git@github.com:openshift/openshift-docs.git
----

This ensures that you are tracking the remote repository to keep your local
repository in sync with it.

== Previewing the documentation locally

After you clone the documentation repository, you are ready to
install the software you need to build our content from source. All OpenShift
documentation is written in AsciiDoc, and is processed with https://github.com/redhataccess/ascii_binder[AsciiBinder],
which is an http://asciidoctor.org/[AsciiDoctor]-based docs management system.

The recommended way to run AsciiBinder is on a container image using link:https://podman.io/[Podman]. However, if you already have Docker on your system, you can use it in place of Podman.

[IMPORTANT]
====
Previously, installing AsciiBinder directly on your system was recommended. However, on recent Linux distribution releases, AsciiBinder does not work because of Ruby version incompatibility.

Use AsciiBinder by running the container image.
====

=== Installing Podman on your system

Install Podman so that you can run the AsciiBinder container image on your machine.

If you are using Fedora, from a command line, enter:

[source,terminal]
----
$ sudo dnf install podman
----

If you are using another operating system, follow the link:https://podman.io/docs/installation[Podman installation docs].

=== Building the documentation

Run the container image with an AsciiBinder command to build the OpenShift documentation.

. From a command line, change to the `openshift-docs` directory.

. To build every distribution in the docs, enter the following command:
+
[source,terminal]
----
$ podman run --rm -it -v `pwd`:/docs:Z quay.io/openshift-cs/asciibinder asciibinder build
----
+
The `asciibinder build` command runs within the image. The AsciiDoc files are transformed into HTML files in your local repository under the `_preview` directory. By default, AsciiBinder generates a documentation set for each distribution.

TIP: To choose which link:https://github.com/openshift/openshift-docs/blob/main/contributing_to_docs/doc_guidelines.adoc#product-title-and-version[distributions] to build, use the `-d` option in the command. For example, to only build  `openshift-enterprise`, change `asciibinder build` to `asciibinder build -d openshift-enterprise`.



== Next steps
With the repository and tools set up on your workstation, you can now either
edit existing content or create assemblies and modules.

* link:doc_guidelines.adoc[Review the documentation guidelines] to understand
some basic guidelines to keep things consistent across our content.
* link:create_or_edit_content.adoc[Create a local working branch] on your
workstation to edit existing content or create content.
