We aim to provide clear, consistent and compelling guidance which will inspire teams and help support them with how to design and deliver great digital services.
https://govau.github.io/service-manual/docs/
The Cuttlebelle auto-docs are deployed to the gh-pages branch.
To update the documentation after changing or adding a partial, change to the gh-pages branch and run npm run docs. Push it to deploy.
https://github.com/govau/backstop-guides-tests
These can be optionally run before a production deployment to visually see the difference.
It's good for non-functional changes to ensure there is no visual regression.
- url: https://service-manual.apps.y.cld.gov.au/
- branch:
develop - status:
- Branches deployed with the '-staging' suffix will be deployed to a new environment.
https://service-manual-[branchname-staging].apps.y.cld.gov.au/- example branch
test-staginghttps://service-manual-test-staging.apps.y.cld.gov.au/
All pull requests should be compared against develop. To keep things simple, opt for the Docker option but the DIY is also provided. First check out the repository:
git clone github.com/govau/service-manual
cd service-manual
Build the Docker image:
service-manual$ docker build -t service-manual .
Run the image:
service-manual$ docker run --rm --volume="$PWD:/workdir" -p 80:8080 -it service-manual
Now point your browser to your docker host with something like http://localhost/
It's recommended you install nvm to manage your local node version.
Change node version
nvm useInstall dependencies
npm installBuild the static assets
npm run buildStart the development server
npm run watchAll content for the Service Manual is in the /content folder. We use Cuttlebelle as static site generator
as to cleanly separate content from layout.
Images for content pages can be stored in the /content/assets folder.
Metadata can be stored on pages within the index.yml file. All fields except for pagetitle are optional.
Fields
pagetitle (string required)- the page title
description (string optional)- the meta description
keywords (string, comma delimited list, optional)- for search engine
created_by (string optional)- is displayed on pages using intro_with_nav
published_date (ISO date yyyy-mm-dd optional)- is displayed on pages using intro_with_nav
- make sure to form as a string e.g. "2018-05-12"
reviewed_date (ISO date yyyy-mm-dd optional)- is displayed on pages using intro_with_nav
- make sure to form as a string e.g. "2018-05-12"
boost (integer optional)- influences the search engine results
hidden (boolean optional)- hides the page if set to true
weight (integer optional)- influences the ordering of menu items
Search is provided by the Lunr javascript search engine.
Weight to search scoring is in the following descending order:
keywords(boost = 30)title(boost = 10)description(boost = 5)body(no boost)
The content is indexed at build time, and can be influenced with the optional metadata fields keywords and boost.
Boost
Use small values, like 0.5 - 1 until your desired search result is attained.
Keywords
Keywords can be added in a comma delimited list.
Federated pages
External pages can be federated by adding data to scripts/federate.js
Special combos
Two word special word combinations can be added to improve results for specific queries. An example is the role 'delivery manager'.
How to add a special combo:
- Append the combination to the
function specialCombos(query)in06-search-results.js. - Add the two word term into the keywords of the page
Search data static files
Search data and indexes are stored in the following static files, which are deployed with the site:
- documents.json (the site document data)
- pathmap.json (lookup table for the SERP)
- search_index.json (lunr's serialised index)
Rebuilding the search index in development
When experimenting with search tuning in development it is necessary to rebuild the search index after changing content or metadata. This can be done hot in another terminal window with Cuttlebelle running.
npm run build:search