Visit live demo.
Create a /docs
folder in your repository
Create the directory to hold your ADRs, and initialize the website.
# Download the boilerplate project so we can tweak it.
npx degit github:e0ipso/adr-website-example#main docs
cd docs
# Install the documentation site.
npm install
# Run the development server.
npm run-script develop
Change customize the Look & Feel
This project uses Gatsby. This means that you can override any of the
components here using a technique
called component shadowing
. The boilerplate you downloaded contains examples of that. See the
contents of the src/@lullabot/gatsby-theme-adr
to change the copyright
information the menu title, etc.
Additionally, you will need to change the images in src/images
to
include the logo for your project.
Finally, edit gatsby.config.js
to remove references to "My Company" and
use your project's info instead.
(Optional) Move Tugboat integration to your project root
If you want to preview your site documentation in
your Tugboat
previews, you can use the configuration in the .tugboat
directory.
If you already use Tugboat adapt your project configuration to add the service for the ADR website instead.
mv .tugboat ../
Open the code and start customizing!
Your site is now running at http://localhost:8000!
Edit src/pages/index.jsx
to see your site update in real-time!
Depending on the CI you use and where you publish the ADR site this process will differ.
Here is an example that assumes you use GitHub Actions for CI and GitHub Pages to host the static site.
Add a workflow for your repository in .github/workflows/gh-pages.yml
with the
following contents:
name: website
on:
push:
# Update this to your branch name.
branches: [main]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v2
with:
node-version: ${{ matrix.node-version }}
- name: Install package dependencies
run: npm ci
- name: Build Gatsby site
run: npm run-script build
- name: Deploy to GitHub Pages
if: success()
uses: crazy-max/ghaction-github-pages@v2
with:
target_branch: gh-pages
build_dir: docs/public
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
See CONTRIBUTING.md for information on how to set up a local environment to work on issues.