Create User and Developer Guides

User and Developer Guides are handy to provide overviews of projects by highlighting useful functions and approaches. In addition, README.md and AGENTS.md files are handy for overiews. Here are some examples:

Table of Contents

Digital Tool Guides & Prompts

Prompts

Guides and Overviews

Documentation Repo Developer Guide

This section serves as the developer guide for managing, editing, and checking the integrity of this Documentation repository.

1. Site Layout & Directory Map

The repository is built as a Jekyll static site using the just-the-docs theme, compiled automatically on GitHub Pages. Quarto is used to build slides.

Documentation/
├── _config.yml                     # Jekyll configuration (remote theme, plugins)
├── _quarto.yml                     # Quarto website output options
├── README.md                       # Main site landing page (index)
├── guides.md                       # Main guides index & repo developer guide (this page)
├── AGENTS.md                       # Workspace conventions and rules for AI agents
├── R/                              # R language tutorials and notebooks
├── python/                         # Python language tutorials and notebooks
├── github/                         # Git and GitHub publishing workflows
├── envsys/                         # Environmental systems data notes
├── datasci/                        # Data science resources
├── AI/                             # AI tool summaries and agents research
├── prompts/                        # System prompts and case studies
├── quarto/                         # Quarto source slides and compiled slide decks
└── scripts/                        # Repository helper scripts
    ├── check_links.py              # Automated link checking script
    └── add_glyphs.py               # Glyphs addition helper

Configuration Files

  • _config.yml: Uses the remote_theme: just-the-docs/just-the-docs. It enables jekyll-relative-links (allowing markdown files to reference each other with standard relative links like [text](folder/file.md)) and auto-generates the side navigation tree based on metadata.
  • _quarto.yml: Configures Quarto slide projects to compile .qmd files in place (output-dir: .) so they can be processed and served alongside Jekyll markdown files.

2. Page Metadata & Frontmatter Standards

To ensure Jekyll organizes the navigation sidebar and breadcrumbs correctly, every markdown and Quarto file must begin with standard YAML frontmatter:

---
title: "The Page Title"                # Shows in navigation menu and page title
parent: "Parent Page Title"           # MUST match the exact title of the parent page (optional)
nav_order: 3                           # Determines layout order under parent (optional)
permalink: /optional/custom/path/      # Absolute URL path override (optional)
---

Folder Conventions

  • Save general conceptual notes as markdown files (.md) inside their respective folders (e.g. github/, AI/, python/).
  • Save slides as Quarto slides (.qmd) under quarto/.
  • Ensure all relative link paths to other documents do not include leading slashes or absolute domain prefixes, so that they render correctly in local previews and on the published GitHub Pages site.

3. Automation & Link Checking

To prevent dead references and broken links as external websites change, use the automated script in scripts/check_links.py to scan the repository.

Run the script from the repository root:

python3 scripts/check_links.py

Features

  • Scans all .md, .qmd, and .Rmd files in the repository.
  • Extracts and checks all http:// and https:// URLs in parallel using threaded execution.
  • If broken links are found, generates a detailed markdown report (link_check_report.md in the root) listing the file, line number, URL, and HTTP status code or connection error.

For more details on link checking parameters (ignoring SSL errors, checking a single file, fetching historical Wayback Machine snapshots), see the Check External Links Guide.

This site uses Just the Docs, a documentation theme for Jekyll.