From 4eff7d5d450c4acdef3249c5d588275c77e4e336 Mon Sep 17 00:00:00 2001
From: Robert Krátký <rkratky@redhat.com>
Date: Dec 03 2017 17:59:17 +0000
Subject: Use HTML mark-up to work around Pagure's borked MD rendering.


---

diff --git a/README.md b/README.md
index c4cd0d7..2a74a90 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ Please report Issues and submit Pull Requests for **Publishing Fixes** here.  Co
 
 ## Testing your changes locally
 
-To test your changes, first install `asciibinder`
+To test your changes, first install <code>asciibinder</code>
 
 ```
 $ sudo dnf install ruby-devel
@@ -34,133 +34,117 @@ Publishing uses two repos:
 
 ### Pre-requisities
 
-1. You need `git` and `asciibinder`.
-
-    ```
-    $ gem install ascii_binder
-    $ sudo dnf install git
-    ```
-
-2. You need both repositories
-
-    ```
-    $ git clone ssh://git@pagure.io/fedora-docs/docs-fp-o.git
-    $ git clone ssh://git@pagure.io/fedora-docs/fedora-docs-web.git
-    ```
+<ol>
+  <li>You need <code>git</code> and <code>asciibinder</code>.
+    <pre>
+$ gem install ascii_binder
+$ sudo dnf install git</pre>
+  </li>
+  <li>You need both repositories
+    <pre>
+$ git clone ssh://git@pagure.io/fedora-docs/docs-fp-o.git
+$ git clone ssh://git@pagure.io/fedora-docs/fedora-docs-web.git</pre>
+  </li>
+</ol>
 
 ### Publishing
 
-1. Go to the `docs-fp-o` repository and ensure you are on master and that it is up-to-date
-
-    ```
-    $ cd <path to docs-fp-o>
-    $ git checkout master
-    $ git pull
-    ```
-
-2. Prepare the repo to be built by loading in all documentation sources.
-
-    ```
-    $ ./builder.sh
-    ```
-
-    This will generate a whole lot of output.
-
-3. Build the site
-
-    ```
-    $ asciibinder package
-    ```
-
-    This will also generate a lot of output.
-
-4. Stage the site
-
-    ```
-    $ cp -r _package/main/* <path to fedora-docs-web>
-    $ cd <path to fedora-docs-web>
-    $ git checkout stg
-    $ git add .
-    $ git commit -m "Updating site"
-    $ git push
-    ```
-
-5. Review the staged site at [docs.stg.fedoraproject.org](https://docs.stg.fedoraproject.org) and see if it looks good.  The site is updated approximately every 5 minutes, so give it time.
-
-6. If you're happy, push the changes to production.
-
-    ```
-    $ git checkout prod
-    $ git merge stg
-    $ git push
-    ```
-
-7. Verify your changes have gone live at [docs.fedoraproject.org](https://docs.fedoraproject.org) and see if they look good.  The production site is refreshed once per hour so this may take some time.
+<ol>
+  <li>Go to the <code>docs-fp-o</code> repository and ensure you are on master and that it is up-to-date
+    <pre>
+$ cd <path to docs-fp-o>
+$ git checkout master
+$ git pull</pre>
+  </li>
+  <li>Prepare the repo to be built by loading in all documentation sources.
+    <pre>
+$ ./builder.sh</pre>
+    <p>This will generate a whole lot of output.</p>
+  </li>
+  <li>Build the site
+    <pre>
+$ asciibinder package</pre>
+    <p>This will also generate a lot of output.</p>
+  </li>
+  <li>Stage the site
+    <pre>
+$ cp -r _package/main/* <path to fedora-docs-web>
+$ cd <path to fedora-docs-web>
+$ git checkout stg
+$ git add .
+$ git commit -m "Updating site"
+$ git push</pre>
+  </li>
+  <li><p>Review the staged site at <a href="https://docs.stg.fedoraproject.org">docs.stg.fedoraproject.org</a> and see if it looks good.  The site is updated approximately every 5 minutes, so give it time.</p></li>
+  <li>If you're happy, push the changes to production.
+    <pre>
+$ git checkout prod
+$ git merge stg
+$ git push</pre>
+  </li>
+  <li>Verify your changes have gone live at <a href="https://docs.fedoraproject.org">docs.fedoraproject.org</a> and see if they look good.  The production site is refreshed once per hour so this may take some time.</li>
+</ol>
 
 ### Branching New Releaess
 
 In each content repository (i.e. https://pagure.io/fedora-docs/install-guide):
 
-1. Go to the master branch
-    ````
-    $ git checkout master
-    ````
-
-2. Branch for the new release, Fedora 27 in this example:
-    ````
-    $ git checkout -b f27
-    ````
-
-3. Update the entities file to reflect the correct version numbers
-    ````
-    $ vi en-US/entities.adoc
-    ````
-
-4. Commit your changes and push to the upstream repository
-    ````
-    $ git add en-US/entities.adoc
-    $ git commit -m "Branching for F27"
-    $ git push upstream f27
-    ````
-
-5. Return to the master branch
-    ````
-    $ git checkout master
-    ````
-
-6. Update the _distro_map.yml file to add the new version
-    ````
-    $ vi _distro_map.yml
-    ````
-
-7. Commit your changes and push to the upstream repository
-    ````
-    $ git add _distro_map.yml
-    $ git commit -m "Branching for F27 - updating _distro_map.yml"
-    $ git push upstream master
-    ````
+<ol>
+  <li>Go to the master branch
+    <pre>
+$ git checkout master</pre>
+  </li>
+  <li>Branch for the new release, Fedora 27 in this example:
+    <pre>
+$ git checkout -b f27</pre>
+  </li>
+  <li>Update the entities file to reflect the correct version numbers
+    <pre>
+$ vi en-US/entities.adoc</pre>
+  </li>
+  <li>Commit your changes and push to the upstream repository
+    <pre>
+$ git add en-US/entities.adoc
+$ git commit -m "Branching for F27"
+$ git push upstream f27</pre>
+  </li>
+  <li>Return to the master branch
+    <pre>
+$ git checkout master</pre>
+  </li>
+  <li>Update the _distro_map.yml file to add the new version
+    <pre>
+$ vi _distro_map.yml</pre>
+  </li>
+  <li>Commit your changes and push to the upstream repository
+    <pre>
+$ git add _distro_map.yml
+$ git commit -m "Branching for F27 - updating _distro_map.yml"
+$ git push upstream master</pre>
+  </li>
+</ol>
 
 In this repo, the builder repository:
 
-Note: In the build directory the beta version is always in the `beta/` directory when published.
+Note: In the build directory the beta version is always in the <code>beta/</code> directory when published.
 
-1. Edit the _distro_map.yml to reflect the addition of the new version.  See the fXX-en-US lines:
+1. Edit the <code>_distro_map.yml</code> to reflect the addition of the new version.  See the fXX-en-US lines:
 
-2. Edit builder.sh to add the new branch to the BRANCHES variable
+2. Edit <code>builder.sh</code> to add the new branch to the BRANCHES variable
 
-3. Edit build.sh to add a new variable to hold the list of content repositories for the new branch.  See f26_BOOKS for an example.
+3. Edit <code>build.sh</code> to add a new variable to hold the list of content repositories for the new branch.  See f26_BOOKS for an example.
 
-4. Edit the index-main.html to link to the new version, as needed.
+4. Edit the <code>index-main.html</code> to link to the new version, as needed.
 
 ### Notes
 
-The `asciibinder` command will incorrectly report that there are nonexistent topics in the `_topic_map.yml`.  This is error is caused by ruby's Find module not following symlinks and is specific to this build repository.  To validate a specific content set, test it with `asciibinder` in its source repository.
+The <code>asciibinder</code> command will incorrectly report that there are nonexistent topics in the <code>_topic_map.yml</code>.  This is error is caused by ruby's Find module not following symlinks and is specific to this build repository.  To validate a specific content set, test it with <code>asciibinder</code> in its source repository.
 
 ## Project Plan
 
 Add new features
 
-  * remove `builder.sh` as new functionality arrives in `asciibinder`
+  * remove <code>builder.sh</code> as new functionality arrives in <code>asciibinder</code>
   * Translations
   * Search
   * CI/CD for automatic publishing and rebuild

