# Publishing Documentation

## Prerequisities

- [Docker](https://docs.docker.com/get-docker/)
- Static file hosting

## Create documentation

Create a directory that contains your documentation. Inside this directory you
should create a file called `mkdocs.yml`. As an example you can create a
directory called `hello-docs` in your home directory (also known as `~`). Below
is a basic example of how it could look.

The `~/hello-docs/mkdocs.yml` file should have the following content:

```yaml
site_name: 'example-docs'

nav:
  - Home: index.md

plugins:
  - techdocs-core
```

And then the `~/hello-docs/docs/index.md` should have the following content:

```md
# example docs

This is a basic example of documentation.
```

## Build documentation

```bash
cd ~/hello-docs/
docker run -it -w /content -v $(pwd):/content spotify/techdocs build
```

You should now have a folder called `~/hello-docs/site/`.

## Deploy to a file server

In order to serve documentation to TechDocs, our Backstage plugin needs to
download the HTML rendered from the
[Create documentation](#create-documentation) step above. This will likely exist
on an external file server, or a storage solution such as Google Cloud Storage.

When deploying documentation, it should be deployed on that file server /
storage solution with the following convention: `{id}/{file}`. For example, if
we wanted to upload the `getting-started/index.html` file for the `backstage`
documentation site, we would upload it to our file server as
`backstage/getting-started/index.html`.

To explain further how this would look like for multiple documentation sites,
take a look at this example file tree that would be represented on your file
server:

```md
/backstage/index.html /backstage/getting-started/index.html
/backstage/contributing/index.html /mkdocs/index.html
/mkdocs/plugin-development/index.html
/mkdocs/plugin-development/debugging/index.html
```

In this file tree, we have two documentation sites available: `backstage` and
`mkdocs`. Each of them expose several pages. Let's say both of these are hosted
on `http://example.com` as the server URL.

When you configure the TechDocs plugin in Backstage to use `http://example.com`
as the file server / storage solution, it will translate the following URLs to
the file server:

| Backstage URL                                             | File Server URL                                         |
| --------------------------------------------------------- | ------------------------------------------------------- |
| https://demo.backstage.io/docs/backstage/                 | http://example.com/backstage/index.html                 |
| https://demo.backstage.io/docs/mkdocs/plugin-development/ | http://example.com/mkdocs/plugin-development/index.html |

Then deploying new sites is easy. It's as simple as copying over the `site/`
folder produced in the [Create documentation](#create-documentation) step above
and copying it over to the file server / storage solution under the ID of the
documentation site. It will then become immediately available in Backstage under
the same ID as you can see in the table above.

So, if the URL to your file server is `http://example.com/`, your
`~/hello-docs/site` folder containing the documentation should be accessible at
`http://example.com/hello-docs/`.

## Configure TechDocs to read from file server

In order for Backstage to show your documentation, it needs to know where you
uploaded it.

Make sure you have Backstage set up using
[TechDocs getting started](getting-started.md)

To point Backstage to your docs storage, add or change the following lines in
your Backstage `app-config.yaml`:

```yaml
techdocs:
  storageUrl: http://example.com
```

You can now start Backstage using `yarn start` and open up your browser at
`http://localhost:3000/docs/hello-docs` to view your docs.
