Support How-To

Requirements
- Install the dependencies directly
- Using our Docker image
Project directory structure

This repository contains the source code for https://docs.rackspace.com/support/ website.

The content is written in Goldmark-style Markdown and AsciiDoc. It is generated by Hugo.

Requirements

To build this site locally, you can either install the dependencies directly on your development machine, or run our Docker image.

Install the dependencies directly

Install Hugo directly

To build the documentation locally, install Hugo and have the hugo command available in your PATH. Use Hugo version 0.73 or newer. You can install hugo by using your system’s package manager. For example, on OSX, type the following command to install hugo with Homebrew:

brew install hugo

For more information about how to install Hugo, see Hugo installation documentation.

Install Asciidoctor directly

The documentation build also requires the Asciidoctor Ruby package to process .adoc files. To avoid having to install Ruby packages as the root user (with sudo), add the following lines to the .bashrc (for Bash Shell) or .zshenv (for Z Shell) in your home directory:

export GEM_HOME=$HOME/.gem
if [ -d $GEM_HOME ]; then \
    export PATH=$GEM_HOME:$PATH; fi

Create the ~/.gem directory:

mkdir -p $HOME/.gem

Now, install Asciidoctor and any additional dependencies:

make install

Build the documentation locally

Build your content locally and check for build errors before submitting a pull request.

Change directory to the root directory of your document repository.
Type the following command:

make build-preview

Start a local web server

To preview documents in a web browser such as Chrome, start the Hugo server on your device.

Hugo has a live serve command that runs a small, lightweight web server on your computer so you can test your site locally without needing to upload it anywhere. As you make changes to files in your project, it rebuilds your project and reloads the browser for you.

To start the Hugo server, perform the following steps:

Change directory to the root directory of your document repository.
Run the following command:

make serve

The Hugo server displays some messages while it starts up. The last line should be:

Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) Press Ctrl+C to stop

You should now be able to access the Support How-To using the generated link. You cannot use the Support How-To dropdown to navigate to your new article. To access your article:

Select the link generated by Hugo.
In the search bar type '/support/how-to/' after the existing local address.
Copy and paste the information from the slug section of your metadata after the '/support/how-to/' text.

This running instance supports live reload. Changes you make to files are automatically updated in your running instance.

Some files may not be supported for live reload. If you are not automatically seeing your changes, you may need to restart the server. You can restart the server by pressing 'ctrl-c' and running make serve again.

Using our Docker image

If you don’t want to install packages directly, you can use our Docker image.

Initializing the Docker image

First, create the Docker image by typing make hugo-docker.

Start the Hugo server in Docker

Next, start the Hugo server by typing make hugo-serve.

If everything is working as expected, you will see output similar to:

                   | EN-US
-------------------+--------
  Pages            |  1002
  Paginator pages  |    94
  Non-page files   |  1025
  Static files     |    60
  Processed images |     0
  Aliases          |   300
  Sitemaps         |     1
  Cleaned          |     0

Built in 786 ms
Watching for changes in /Users/ravi7895/workspace/rackerlabs/support-how-to/{archetypes,content,layouts,static,themes}
Watching for config changes in /Users/ravi7895/workspace/rackerlabs/support-how-to/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

You should now be able to access the Support How-To, for example, from: http://localhost:1313/

This running instance supports live reload. Changes you make to files should be automatically updated in your running instance.

Some files may not be supported for live reload. If you are not automatically seeing your changes live you may need to restart the server. You can restart the server by pressing 'ctrl-c' and running make hugo-serve again.

Project directory structure

├── [archetypes]- Directory where you define the content, tags, categories, etc.
├── [content] - Directory that contains the content of the site.
│   ├── [contribute]
│   ├── [documentation]
├── [data] - Directory that contains site data such as localization configuration.
├── [layouts] - Directory that contains Go HTML/template library used to template and format the site.
├── [public] - (Doesn't exist until generated) Directory that contains the generated content for the site.  Should be part of your git.ignore file.
├── [scripts] - Directory that should scripts for generating swagger, tags, etc
├── [static] - Directory for any static files to be compiled into the web site (style sheets, JavaScript, images, robots.txt, fav icons, etc.).
├── [themes] - Directory that contains the site theme.  Themes override layouts.
├── Makefile
├── hugo/Dockerfile - the Dockerfile used to build the Hugo+AsciiDoctor image
├── config.toml - Main configuration file, where you define the web site title, URL, language, etc.
├── README.adoc (This file)

samuel-280589/support-how-to