johannesmarx/docs.pact.io

Pact documentation website

Pact Docs Website

Table of Contents

1. Local development
2. Adding pages
3. Moving pages
4. Automatic syncing from the markdown files in each Pact implementation repository
5. Slack history
6. Hosting
7. Search
8. Contributing
9. Contact

Local development

The files are markdown, stored under the docs directory.

You will need Docker and Docker Compose to run the docs application locally.

docker-compose up

Adding pages

• Add the file to the appropriate path under the docs directory.
• Update website/sidebars.json.

Moving pages

• Find the file under the docs directory.
• Move it to the directory/name you want.
• Update website/sidebars.json.
• Do a file search and replace to update any internal references to the page.
• Create a redirect in netlify.toml.

Automatic syncing from the markdown files in each Pact implementation repository

The markdown files in the following directories are synced from their respective source repositories. Do not edit them directly! You'll be able to tell if it's a file that has been synced from another repository because the custom_edit_url will be set in the page metadata.

• docs/implementation_guides/go
• docs/implementation_guides/javascript
• docs/implementation_guides/jvm
• docs/implementation_guides/python
• docs/implementation_guides/cpp
• docs/implementation_guides/rust
• docs/implementation_guides/net
• docs/pact_broker/client_cli
• docs/pact_broker/docker_images/

Each of the above Pact repositories has a Github workflow that triggers the sync-docs workflow when any markdown files are edited on master.

When the sync-docs workflow runs, it pulls in the master markdown files from the changed repository, syncs and processes them, and then commits and pushes them. On push, Netlify automatically deploys.

Slack history

Because the free version of slack only lets you read the last 10k of messages, and at the time of writing this (March 2021) that means about 97k messages are gone, it's helpful to have access to the history.

You can docs.pact.io/slack/

To update the export:

1. Download the latest extract from https://pact-foundation.slack.com/services/export
2. Extract into a directory
3. Download this php file (to e.g. slack.php) into the same directory as the export: https://gist.github.com/mefellows/1b825c86b2ff1063afbb2e5cb6b8cb3e
4. Run this script php slack.php
5. Sync the HTML files from slack2html/html/* into the website/static/slack directory

Hosting

The Pact docs site is hosted by Netlify. Thanks!

The site will be automatically redeployed after any push to master.

Search

The search is provided free by Algolia because Pact is an open source project.

1. An algolia crawler is defined here to crawl the docs.pact.io sitemap here
2. An algolia search index is configured here and the crawler results are stored in the search index
3. The docs.pact.io website which is built on docusaurus, is configured
   1. in ./website/docusaurus.config.js under themeConfig.algolia
4. The Search analytics page is here.
   1. It is accessed via the pact-foundation@googlegroups.com account

• Info on how to style the search UI is here.

Contributing

See CONTRIBUTING.md

Contact

• Pact Foundation Slack workspace
• Twitter