Set up and work locally
8 minute read
If you are a maintainer of this documentation site, or a contributor who will be making frequent or major contributions to the documentation, we recommend you set up and build the site locally on your computer. This enables you to easily test changes locally before pushing to GitHub.
Set up environment and install required tools
Before you can build the site locally you must set up an environment and install the following tools.
- Git client - This is how you will interact with the GitHub repository.
- Hugo (extended version) - This is the static site generator that builds the HTML site from Markdown.
- Docsy - This is a documentation theme for Hugo.
- NodeJS - This is required by the Docsy theme to install the PostCSS dependencies using
Although you can build the site on Windows or macOS, it is strongly recommended to use a Linux distribution, as this is what is used to build the production site on Netlify.
Windows Subsystem for Linux
If you are unfamiliar with Linux environments, you can get up and running very quickly by installing the Windows Subsystem for Linux (WSL).
To install WSL on Windows 10, follow the WSL installation guide on Microsoft Docs. This guide describes how to:
- Enable the WSL feature in your Windows 10 installation.
- Download and install a Linux distribution from the Microsoft Store. Select Ubuntu 18.04 LTS.
- Initialize the Linux distro, including how to launch it for the first time, how to set up a Linux user account, and how to update and upgrade the packages in the distro.
It is important that you complete all of the steps in the WSL installation guide before proceeding.
TipLearn how to configure your Ubuntu WSL shell in Ubuntu tips.
Gitbash on Windows
If for some reason you cannot use WSL or another Linux distribution, you can install and use Gitbash for Windows. In this case, you will need to use the Gitbash terminal to enter commands instead of the WSL terminal.
Create a GitHub account and set up SSH keys
If you do not already have a GitHub account, go to Sign up to create one.
Generate SSH keys
Launch WSL and generate a new SSH key pair:
ssh-keygen -t ed25519
Press Enter when prompted for a path and a passphrase. You can find more detailed information in Generating a new SSH key pair.
Add SSH key to your GitHub account
On GitHub, click the drop-down next to your profile photo at the top right, and select Settings > SSH and GPG keys.
Click New SSH key.
In WSL, enter the following to print the SSH key in your terminal:
Copy and paste the key from your WSL terminal to the Key text box on GitHub and enter a memorable name for the key in the Title field. Click Add SSH key to save it.
Fork or clone the Axway-Open-Docs Git repository
You have two options to clone the the axway-open-docs Git repo to your local machine:
- Clone the Axway-Open-Docs repository directly. This requires that you have write permissions on the repository to make any changes.
- Fork (make a copy) of the Axway-Open-Docs repository in your personal GitHub account and clone the fork. To fork the repository, follow the steps in Fork a repo.
To clone the Axway-Open-Docs repository directly, enter the following commands in WSL:
cd ~ git clone --recurse-submodules --depth 1 email@example.com:Axway/axway-open-docs.git
If you have forked the Axway-Open-Docs repository, enter the following commands to clone your fork of the repo instead:
cd ~ git clone --recurse-submodules --depth 1 firstname.lastname@example.org:YOUR-USERNAME/axway-open-docs.git
NoteIn both cases, you must use
--recurse-submodulesor you will not pull down the Docsy theme code you need to generate a working site.
After running these commands, you will have a local copy of the repository in the following location:
You need a recent extended version (version 0.53 or later) of Hugo to build and run the site. If you install from the Hugo releases page, make sure to get the
extended Hugo version, which supports SCSS.
Enter the following commands in WSL to download and unpack the Linux 64 bit deb package:
wget https://github.com/gohugoio/hugo/releases/download/v0.56.3/hugo_extended_0.56.3_Linux-64bit.deb sudo dpkg -i hugo_extended_0.56.3_Linux-64bit.deb
NoteDo not use
sudo apt-get install hugoto install on Linux, as it does not always get you the
For full installation instructions for other platforms, see Install Hugo.
To upgrade to a later version of Hugo, for example v0.66.0, enter the following commands to install the later version over your existing version:
wget https://github.com/gohugoio/hugo/releases/download/v0.66.0/hugo_extended_0.66.0_Linux-64bit.deb sudo dpkg -i hugo_extended_0.66.0_Linux-64bit.deb
To verify what version of Hugo you are running, enter:
$ which hugo /usr/local/bin/hugo $ hugo version Hugo Static Site Generator v0.66.0-78C3C78F/extended linux/amd64 BuildDate: 2020-03-03T15:28:32Z
Install NodeJS and PostCSS
You need a recent version (10.x or later) of NodeJS so you can use
npm to install PostCSS.
Enter the following commands in WSL to install NodeJS version 10.x:
curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash - sudo apt-get install -y nodejs
See Node.js Binary Distributions for instructions for installing other versions on Ubuntu.
Enter the following command in WSL to install PostCSS using
cd ~/axway-open-docs sudo npm install
Build the site locally
hugo server command in your site root:
cd ~/axway-open-docs/ hugo server
The website is now available locally at
Make changes locally
You can now add or edit Markdown files in the
content\en\docs\ directory and Hugo will automatically rebuild the site with your changes.
For editing Markdown we recommend using VSCode with the following extensions:
- Code Spell Checker
- Markdown Shortcuts
- Remote Development pack (work with files on WSL from VSCode on Windows)
When you are ready for your changes to be reviewed:
- In your Git CLI client,
pushyour files to the remote Git repo.
- Create a pull request to enable a site maintainer to review the changes you made on your feature branch or fork and pull them into the original Axway repository.
Protect sensitive information
git-secrets on your repository to prevent committing secrets and credentials. For more information, see git-secrets.
Open an Ubuntu WSL window, and change the directory to
Run the script. You will be asked for your Ubuntu password:
You should see a result similar to:
Clone/update the git-secrets Install git-secrets [sudo] password for amussap: Registering git-secrets as a global option Install the git hooks to use with git-secrets Success!
To verify that your
git-secrets installation is working:
Create a feature branch:
git checkout -b testgitsecrets
Create or change a file, for example, adding an AWS secret or credential to it.
Try to commit your change:
git add . git commit -m "add AWS key to my page"
You should see an error similar to:
content/en/docs/contribution_guidelines/testgitsecrets.md:5:AWS_AUTH_ACCESSKEY = <Your AWS authorization key> [ERROR] Matched one or more prohibited patterns Possible mitigations: - Mark false positives as allowed using: git config --add secrets.allowed ... - Mark false positives as allowed by adding regular expressions to .gitallowed at repository's root directory - List your configured patterns: git config --get-all secrets.patterns - List your configured allowed patterns: git config --get-all secrets.allowed - List your configured allowed patterns in .gitallowed at repository's root directory - Use --no-verify if this is a one-time false positive
Tips for configuring Ubuntu WSL
If you are used to working on Windows, Ubuntu WSL can be hard to get used to at first. Follow these tips to make working in Ubuntu easier.
Work with Windows files from Ubuntu
In Ubuntu WSL your Windows file system (your
c: drive) is available under the location
/mnt/c, so for example to access your
Documents folder on Windows you have to
/mnt/c/Users/WINDOWS_USERNAME/Documents/ on WSL.
To make it easier to access Windows files from Ubuntu, you can set up symlinks as follows:
Open an Ubuntu WSL window. By default it opens in your Ubuntu home directory (
/home/USERNAMEor the shortcut
Create a symlink to your Windows
ln -s /mnt/c/Users/WINDOWS_USERNAME/Documents ~/docs
This creates a symbolic link to
~/docs. The command does not print any output.
After the symlink is created, you can change to your Windows
Documentsdirectory using the
From your home directory in Ubuntu, enter:
Or from any other directory, enter:
Repeat step 2 to create additional symlinks to the Windows directories that you use most often.
Configure the Ubuntu prompt
Download the file
git-prompt.shand save it to your
Documentsdirectory on Windows. To download the file, right-click the Raw button at the top of the file and select Save link as…, and then open the file to check that it contains only the raw text and not HTML.
Open an Ubuntu WSL window.
git-prompt.shfile to the home directory in your Ubuntu file system and rename it as
cd ~ cp /mnt/c/Users/WINDOWS_USERNAME/Documents/git-prompt.sh .git-prompt.sh
Launch Visual Studio Code from Ubuntu:
Open the file
.bashrcin VSCode. This file already exists in your Ubuntu home directory and is run each time you open an Ubuntu window to initialize your shell environment.
Paste the following lines at the end of the file:
if [ -f ~/.git-prompt.sh ]; then source ~/.git-prompt.sh export GIT_PS1_SHOWDIRTYSTATE=1 export PS1='\u@\h \[\033[38;5;11m\]\w\[\033[38;5;14m\]$(__git_ps1 " (%s)")\[\033[00m\]$ ' fi
Close the current Ubuntu WSL window and open a new one. This forces Ubuntu to load the changes in
After completing these steps, the command prompt in Ubuntu shows useful information such as the current Git branch, the status of the working directory, and so on.
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.