Skip to content

Setting up your local test website and Asciidoctor

Jump to bottom
Laura Cowen edited this page Dec 1, 2017 · 3 revisions

(Written in Markdown but needs converting to Asciidoc for ease of editing.)

When you make a change to a guide on the Open Liberty website, test that the guide displays correctly before you publish the change.

What? How?
Check the guide transforms to HTML correctly without any errors. Install and run Asciidoctor on your computer OR run Asciidoctor using Docker
Check the guide transforms to HTML correctly and the content looks right on the Open Liberty website. Install and run a local test website OR install and run a local test website using Docker

You can install the test software on your computer directly or you can install Docker and use the preinstalled Docker image so that you don't have to install all the pre-requisite software.

Local test website

Testing in a local test website means that your guide gets transformed to HTML from .adoc and is presented with the full OpenLiberty.io website stylesheet so that you can see it as it will be published. New guides should definitely be tested like this before publishing. Ideally all guides should be checked like this before publishing changes. But running the local test website for all editing changes might be a bit slow (as the whole website gets rebuilt every time you make a change). While you're just editing a guide, you might prefer to take the Asciidoctor-only approach (see further down the page).

Setting up a local test website on your computer

If you want to take this approach, you can install Jekyll on your computer. This requires a whole set of prerequisite software (inc. Ruby, Bundler, make, and so on). Also, Jekyll isn't really supported on Windows.

So I created a Docker image to do all this for you...

Setting up a local test website using Docker

[Note that we are still testing this, especially on Windows which seems to require that you restart the Docker container each time you want to see a change you've made.]

Using Docker means that you don't need to install all the pre-requisite software (like Jekyll, Ruby, and relevant Jekyll gems) because the Docker image already has it all installed for you.

  1. Install Docker.

  2. Download a Docker image containing all the software you need to run a local test site of OpenLiberty.io. In a terminal: docker pull lauracowen/jekyll

  3. Create a directory to work in. For example, I'm working in /Users/laura/github/openliberty/ so substitute your directory path when you see that in the examples below.

  4. In a terminal, move to the directory you just created: git clone https://github.com/OpenLiberty/openliberty.io

  5. In the terminal:

    Mac/Linux: docker run --name jekyll_site -it -d -p 4000:4000 -v /Users/laura/github/openliberty/openliberty.io/src/main/content:/home/jekyll lauracowen/jekyll

    Windows: docker run --name jekyll_site -it -d -p 4000:4000 -v /c/Users/laura/github/openliberty/openliberty.io/src/main/content:/home/jekyll lauracowen/jekyll

  6. In a web browser, visit: http://localhost:4000 (it might take up to 40 seconds to start properly so give it a minute) Check that you can see the Open Liberty website, which is running on your local machine in Docker, in your browser. If you navigate to the Guides section of the site, there are no guides. That's because the guides live in separate git repositories and you haven't cloned them yet.

  7. In the terminal, move to the content part of your local copy of the Open Liberty website: cd openliberty.io/src/main/content

  8. Create a directory called guides. In the terminal: mkdir guides

  9. Move to the directory: cd guides

  10. Clone the openliberty/guides-common repository. This contains common files that all the guides use; you probably won't be editing it so you can just clone the original for your test environment: git clone https://github.com/OpenLiberty/guides-common.git

  11. When you fork and clone another guide that you want to edit, the new guide should be automatically picked up and added to the website:

  12. After cloning the guide, wait a few seconds then, in your browser, visit http://localhost:4000/guides and the guide should now appear on the page. Click the guide to go its webpage.

  13. Make a change to the text in README.adoc file.

  14. Wait a moment then refresh the web browser. Your change should automatically have been rebuilt and displayed in your local test website.

To speed up the rebuild (optional)

(I've not tried this yet) It takes almost 40 seconds to build the Jekyll site. The reason for that is because there are a number of optimizations that take place (minification of CSS/JS/HTML). Within the dev environment, those optimizations aren't really necessary, so you can safely turn them off by switching the following values in the _config.yml file that is in that same directory as the guides directory:

  • assets: compress: css: false
  • assets: compress: js: false
  • minify_html: false

(Just make sure not to deliver these changes to GitHub.) You might need to stop and restart the Docker container to pick up the changes: docker restart jekyll_site

Asciidoctor only

If you prefer not to test in the full website, you can just test with Asciidoctor. The benefit of just testing with Asciidoctor is that it is much quicker to re-run the adoc-to-HTML transformation and refresh your browser for each edit you make to the .adoc file. The downside is that Asciidoctor just uses the default stylesheet so you can't see the guide as it will look when published on the OpenLiberty.io website.

Setting up Asciidoctor on your computer

Here's how to install Asciidoctor on your computer. Again, it has prerequisite software (inc. Ruby, Bundler, and so on).

The nice people at Asciidoctor created a Docker image to use instead...

Setting up Asciidoctor using Docker

  1. Install Docker.

  2. Download a Docker image containing all the software you need to run Asciidoctor against your guide text files (README.adoc). In a terminal: docker pull asciidoctor/docker-asciidoctor

  3. In a terminal, start the Docker container (where /Users/laura/.... is the location of the README.adoc file that you are editing:

    docker run --name asciidoctor -it -v /Users/laura/github/openliberty/openliberty.io/src/main/content/guides/guide-rest-intro:/documents/asciidoctor/docker-asciidoctor asciidoctor/docker-asciidoctor

    The Docker container starts and in your terminal a bash session starts (you are now inside the Docker container).

  4. In the terminal, move to the directory in the Docker container that is mapped to the location of your README.adoc file: cd asciidoctor/docker-asciidoctor/ (I don't know why this doesn't happen automatically at the moment.)

  5. Run Asciidoctor to transform the README.adoc file to HTML: asciidoctor README.adoc

  6. On your local computer, you should now see a new file called README.html in the same directory as the README.adoc file. Open the README.HTML file in a web browser. Ta-da!

  7. Keep editing the README.adoc file. Whenever you want to check it in the browser, in the terminal just re-run asciidoctor README.adoc, then press F5 to refresh the HTML page in your web browser.

If you want to stop the Docker container:

  1. In the terminal, leave the bash session in the Docker container: exit.
  2. Stop the Docker container: docker stop asciidoctor
  3. To start the Docker container again next time: docker start asciidoctor
Clone this wiki locally