This repo contains the Gatsby application that powers EDB's documentation website, as well as the advocacy content. The site pulls additional content from other repos, in a process called 'sourcing'.
Installation
- Clone the repo!
- (MacOS) Install the homebrew package manager, if it's not already installed.
- Install Node.js. We're currently using Node.js version 12. To install this version, first install
nvm
(Node Version Manager). This can be done with (MacOS)brew install nvm
, followed bynvm install
. Optionally, you can skip installingnvm
and install Node.js 12 directly if you prefer. - Install Python 3.6 or higher (this is not needed for the core system, but is required by several source scripts)
- Install yarn and gatsby with
npm i -g gatsby-cli
andnpm i -g yarn
- Install all required packages with
yarn
- Pull the shared icon files down with
git submodule update --init
- Select sources with
yarn config-sources
(see section below for details) - Pull sources with
yarn pull-sources
(see section below for details) - Run the site locally with
yarn develop
. The site should now be running athttp://localhost:8000/
!
Running without a local installation
If you wish to work with Docs without installing the prerequesites locally, you can do so from within a Docker container using VSCode. See: Working on Docs in a Docker container using VSCode
Sources
- Advocacy (
/advocacy_docs
, always loaded) - Product Docs (
/product_docs
) - Kubernetes Docs (https://github.com/EnterpriseDB/edb-k8s-doc)
- 2nd Quadrant BaRMan (https://github.com/2ndquadrant-it/barman)
Configuring
When doing local development of the site or advocacy content, you may want to load other sources to experience the full site. The more sources you load, the slower the site will build, so it's recommended to typically only load the content you'll be working with the most.
yarn config-sources
Run yarn config-sources
to setup your dev-sources.json
file. This file tells Gatsby which sources to load, and also provides the next script yarn pull-sources
with the data it needs. The script is interactive!
Alternatively, you can setup your dev-sources.json
file manually by copying dev-sources.sample
to dev-sources.json
, and editing as desired. The sample file will source everything by default.
yarn pull-sources
Use this command to pull down all the sources you have specified in your dev-sources.json
file. This will wipe all external sources, so make sure you do not have any local changes to these files that you want to save! The /advocacy_docs
and /product_docs
folders will not be affected.
Resolving issues
If you experience errors or other issues with the site, the first step you should take is to run yarn clean
, and then try yarn develop
again. This clears gatsby's cache, and can often resolve strange issues.
Development
All changes should have a pull request opened against the default branch, develop
. When a pull request is opened, Heroku should automatically create a review build, which should be linked in the pull request under "deployments". Review builds only include advocacy content. When a pull request is merged, develop
will automatically deploy the changes to the staging environment.
To deploy to production, create a pull request merging develop
into main
. When that PR is merged, main
will automatically build and deploy to the production site.
Environment Details
Deployments of the site use the build-sources.json
file to determine which sources need to be loaded. All environments are continuously deployed - new commits to relevant branches will trigger a build of the associated environment. The builds are done using Github Actions, so you can view deployment progress by clicking the "Actions" tab.
Staging
Staging is hosted on Netlify, and is built from the develop
branch. The build and deployment process is handled by the deploy-develop.yml
GitHub workflow.
Production
Production is hosted on Netlify, and is built from the main
branch. The build and deployment process is handled by the deploy-main.yml
GitHub workflow. The production deployment process will update the search index on Algolia.
Review Builds
Review builds are automatically created for pull requests. These builds are created by Heroku, and only include advocacy content, no other sources.
Advocacy Docs
Advocacy doc files are in advocacy_docs/getting-started
New docs need a .mdx
suffix to be used by Gatsby.
frontmatter
Each document requires a frontmatter
section at the top with a title. This looks like this:
---
title: Title of page
---
The title can be in quotes, but they are not needed unless you want an apostrophe in there. There also needs to be a space after title:
In addition to title
, there is also the option of adding navTitle
and description
to look like this:
---
title: An exhaustive guide to all things wonderful about Postgres
navTitle: Postgres guide
description: Everything you need to know about Postgres
---
The navTitle
is used for the left navigation so it can take up less space. It is also used in "cards".
The description
is used in cards as well.
Markdown styling
All of these files use Markdown for styling. The options for what can be done can be seen here
Ordering of files
The items in the left nav are sorted alphabetically by file name. This can be done with a numerical prefix. The titles of each page are used for the names in the left nav.
Content submission
To add content to this site, changes must be submitted as a PR. There are two options for this:
Option 1: locally
- Clone repo
- Make a new branch
- Add commits to branch and push to github
- Create a new PR on github
Option 2: on github
- Edit a file on github
- Submit changes as a PR on a new branch
Search
Content is indexed for search when the production site builds.