Technical Blog

• Requirements
  • Local set up
• Project directory structure

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

The website is written in AsciiDoc, generated by using Hugo, and hosted on GitHub.

Requirements

The Docs site runs on top of Hugo. To run an instance locally you need to either install Hugo and AsciiDoctor locally.

Local set up

 npm i -g netlify-cli
 netlify init
 netlify build
 netlify dev
 netlify deploy

Install Hugo and AsciiDoctor locally

If you want to install the required tools, you must first install Hugo and have the hugo command available in your PATH. Use Hugo version 0.78 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 please see the installation documentation.

You also need Asciidoctor and Gem to run the local Docs site. Install those tools and verify them by running the following commands:

install asciidoctor: sudo gem install asciidoctor -N verify asciidoctor -v verify gem —help

Alternatively, use the make install command to install Asciidoctor by using Ruby Gem and Bundler. You need to have the gem command in your path. For more information, see the Ruby Gem installation docs.

Build the documentation locally

Build your content locally and check for build errors.

1. Change directory to the root directory of your document repository.

2. Run the following command:

netlify build

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:

1. Change directory to the root directory of your document repository.

2. Run the following command:

netlify dev

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 technical blog using the generated link. You cannot use the Technical blog dropdown to navigate to your new article. To access your article:

1. Select the link generated by Hugo.

2. In the search bar type '/blog' after the existing local address.

3. Copy and paste the information from the slug section of your metadata after the '/blog/' text.

This running instance should support 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 netlify dev again.

If everything is working as expected you should see output similar to the following example:

Start building sites …
hugo v0.84.2+extended darwin/amd64 BuildDate=unknown

                   | EN-US
-------------------+--------
  Pages            |  1466
  Paginator pages  |   199
  Non-page files   |  1759
  Static files     |    43
  Processed images |     0
  Aliases          |   406
  Sitemaps         |     1
  Cleaned          |     0

Built in 2232 ms
Watching for changes in /rackerlabs/technical-blog/{archetypes,content,i18n,layouts,static}
Watching for config changes in /rackerlabs/technical-blog/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 //localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

   ┌─────────────────────────────────────────────────┐
   │                                                 │
   │   ◈ Server now ready on http://localhost:8888   │
   │                                                 │
   └─────────────────────────────────────────────────┘

You should now be able to access the technical blog, for example, from: http://localhost:1313/blog/

This running instance should support 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 netlify dev again.

Project directory structure

├── [archetypes]- Directory where you define the content, tags, categories, etc.
├── [content] - Directory that contains the content of the site.
├── [i18n] - Directory that contains localization files.
├── [src] - Directory for any JavaScript files to be compiled into the web site.
├── [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.
├── [static] - Directory for any images to be compiled into the web site.
├── [assets] - Directory for any style sheets to be compiled into the web site.
├── Makefile
├── config.toml - Main configuration file, where you define the web site title, URL, language, etc.
├── README.adoc (This file)