CONTRIBUTING.md

Contributing

Developing

• The site is maintained as an MkDocs website using the Material for MkDocs theme
  • See mkdocs.yml
• The site source is contained in the src/ directory
  • This is configured in mkdocs.yml
  • Differed from the default (docs/) to reflect that this site is not documentation
• Dependencies are managed using Poetry for Python
  • See pyproject.toml
• Common tasks are defined using Taskfile
  • See Taskfile.yml

Testing

The site can be tested locally using mkdocs serve once Python dependencies are installed.

# Install Python dependencies
poetry install --no-root

# Serve the site locally
poetry run mkdocs serve

The "serve" task can automatically perform these steps.

# Run the "serve" task
task serve

Deploying

• The site is deployed to GitHub Pages using GitHub Actions
• The custom domain "justenstall.com" is managed by CloudFlare

To trigger a deployment

Troubleshooting

• macOS systems can show error for a missing "cairo" library, with various names. brew install cairo should resolve the errors.

The repository uses Git LFS for image storage, if you have not installed and set up Git LFS before cloning the repository, the images will download incorrectly.

The easiest way to resolve it is to delete the clone and re-clone the project.

There is an open issue for a more elegant solution from Git LFS: git-lfs/issues/325