This repo contains the React/Gatsby application that powers the EDB Docs website. The site pulls Markdown content from several repos in a process called "sourcing", and then renders it all into high-performance markup. You can install the application on your local computer for easy editing, viewing, and eventually publishing to the GitHub repo.
We recommend using MacOS to work with the EDB Docs application.
-
Install Homebrew, if it's not already installed. (Use
brew -v
to check.) -
Install Git using Homebrew with
brew install git
, if it's not already installed. (Usegit --version
to check.) -
Set up an SSH key in GitHub, if you haven't done so already. (Go to GitHub's SSH Keys page to check.) If you don't have an SSH Key set up yet, you'll need to set one up to authenticate you to GitHub. See GitHub's SSH docs for more information.
-
Clone the EDB Docs GitHub repo to your local machine using GitHub Desktop, or via the Terminal with
git clone https://github.com/EnterpriseDB/docs.git
-
Navigate to the cloned repo directory in your Terminal, if you haven't already done so.
-
Install Node.js version 14 LTS. We recommend using Node version 14 LTS (the Long Term Support release) as version 15 is not compatible with some of our dependencies at this time.
-
If you already have Node installed, you can verify your version by running
node -v
in the cloned repo directory. -
If you already have a different version of Node installed, you may want to consider using Node Version Manager (NVM) for a simpler way to manage multiple versions of Node.js. Follow the directions to install NVM, then run
nvm install
in the cloned repo directory, followed bynvm use
which will auto-detect the correct version of Node.js to use (currently 14 LTS).
-
-
Install Python 3 with
brew install python3
, if it's not already installed. (Usepython3 -V
to check that you have version 3.6 or higher.) Python is not needed for the core Gatsby system, but is required by several source scripts. -
Install Yarn with
npm i -g yarn
. Yarn is the package manager we're using for this project, instead of NPM. -
Install Gatsby with
npm i -g gatsby-cli
. Gatsby is the software that powers the EDB Docs site. -
Install all required packages by running
yarn
. -
Pull the shared icon files down with
git submodule update --init
. -
Now select which sources you want with
yarn config-sources
. -
And finally, you can start up the site locally with
yarn develop
, which should make it live athttp://localhost:8000/
. Huzzah!
If you are a Windows user, you can work with Docs without installing it locally by using a Docker container and VSCode. See Working on Docs in a Docker container using VSCode
-
Advocacy (
/advocacy_docs
, always loaded) -
EDB Product Docs (
/product_docs
)- For a list of these sources, see product_docs/docs
-
GitHub-Sourced Docs (entirety of
/external_sources
at present)
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.
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.
If you select an "external" source, you will be prompted to run the next command, yarn pull-sources
, to download and load this content from the internet.
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 (in the external_sources
subdirectory) that you want to save! The /advocacy_docs
and /product_docs
folders will not be affected.
Advocacy Docs are tutorial content, getting-started material, and anything that is about a subject matter area, but not explicitly tied to a product version.
Product Docs are versioned documentation for products. They follow a slightly stricter file structure to allow for version switching and other features.
GitHub Docs are a low-touch way to display markdown content from GitHub. These docs will link back to the relavent GitHub url on each page, in order to provide any missing context.
More details can be found on the Adding New Sources page.
See Adding New Sources for a guide to choosing a source type, adding the files, and other configuration.
If you experience errors or other issues with the site, try the following in the project folder:
rm -rf node_modules
to clean out installed JavaScript packagesyarn
to reinstall JavaScript packagesyarn clean
to clean up Gatsby cacheyarn develop
to start the development environment again. Keep in mind this will take longer than usual as Gatsby will need to rebuild everything.
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.
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 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 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 are automatically created for pull requests. These builds are created by Heroku, and only include advocacy content, no other sources.
Advocacy doc files are in advocacy_docs/getting-started
New docs need a .mdx
suffix to be used by Gatsby.
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.
All of these files use Markdown for styling. The options for what can be done can be seen here
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.
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
Content is indexed for search when the production site builds.