IMPORTANT: Before contributing to this project, read and agree with our code of conduct.
To build the project locally, you either need Hugo or Docker to be installed. In this section, we document the Docker usage. If necessary, read the official Hugo documentation for getting started without Docker.
Fork and clone the project from GitHub. Current theme is included in the project as a sub-module which must be fetched as well.
# Replace the <USERNAME> with your GitHub account name after forking.
git clone [email protected]:<USERNAME>/documentation.git
cd documentation && git submodule update --init --recursive --remoteProject is bundled with Dockerfile and docker-compose.yml for building it without dependencies.
To build the image and launch a development container:
docker-compose up --build -d
open http://localhost:1313To build a production-like image and launch an nginx server serving the static content:
docker build -t paytrail/documentation .
docker run --rm -dit --name hugo-nginx -p 8080:8080 paytrail/documentation:latest
open http://localhost:8080Documentation pages are placed in the content/ subdirectory as Markdown (*.md) files. The URL structure mimics the directory paths, so for example E2 interface validation guide is found under content/payments/e2-interface/validation.md.
To create a new page, either use the hugo new command within the Docker container or create the file manually.
Hugo content sections assume the page markdown is either in the directory index file or a standalone Markdown file. You can either create a /section/_index.md file or /section.md file directly. We recommend using index files as top-level pages and the rest as their child pages.
Besides standard pages, selected pages may appear as root pages on the main page with a title, icon, and short description.
Static assets like images should be placed under the static/ directory. The build will copy these files to the site root. In production these are served from a fast CDN (e.g. Netlify uses Amazon CloudFront).
Each page should contain a valid YAML metadata block or header which looks like this:
# Standard Page
title: My Cool Page
draft: false
weight: 1
# Root page
title: "Frequently Asked Questions"
description: "Ask anything from us!"
icon: "ti-credit-card"
draft: false
type: docs
weight: 5The following YAML keys are supported.
title– title shown for each page with a HTML header tagdescription– description shown in the main page under the iconicon– a valid Themify icon code shown in the main pagedraft– valuetrueensures the page is not visible in the production build (for convenience, the page is visible when developing locally and in pull request preview deployments)type– when set todocsthe page is displayed on the main page as a box with title, icon, and descriptionweight– defines the order of pages in the page tree, lower weight ranks the page higher
Hugo supports shortcodes which you can use to enhance your Markdown in addition to standard syntax. The included theme may also provide their own shortcodes which you should get familiar with. Hugo documentation has more information about creating your own shortcodes if necessary.
Example Shortcodes
Shortcodes are wrapped in double curly braces and <>. Hugo parses these when building the site and displays an error in the browser if the used shortcode can't be parsed.
For example, you can create Markdown links like so:
[Neat]({{< ref "blog/neat.md" >}})
[Who]({{< relref "about.md#who" >}})Another use case for shortcodes is placing images (figures) on the page like so:
{{< figure src="/images/awesome.png" alt="Paytrail is Awesome" width="75%" >}The figure shortcode accepts width and height as parameters which can be adjusted to align the figure with the content.
The main page includes a dynamic search widget which queries pages from an index. The index is constructed on build and favours keywords found in the content body. We recommend thinking one or more essential keywords which visitors could use while searching the content and adding these to the Markdown.
Whenever a new pull request is opened to this repository, Netlify creates a preview deployment from it. In addition to general build errors, Netlify checks for header rules, mixed content (HTTPS referencing HTTP), and redirect errors. Before handing the pull request over for a review make sure all the checks pass. Reviewers use the preview deployment to judge if changes should be integrated to the site.
The production site mirrors the master branch and there are no special release branches or tags for this.