diff --git a/AGENTS.md b/AGENTS.md index 204465c..c510ea3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -88,14 +88,21 @@ repository: to the core principles, especially being code-independent. - **Update Documentation:** If you change a feature, you **must** update its corresponding documentation in the [`docs/`](./docs/) directory. - If you add a new feature, you **must** create a new documentation file for - it, following the namespace and dual-TOC structure. This means: - 1. Identify the correct namespace for your documentation (e.g., `development`, `workflows`). - 2. Create a new file named `docs/..md`. - 3. Add a link to your new file in **two** places: - - The main Table of Contents in `docs/README.md`, under the appropriate namespace heading. + All documentation must follow these rules: + 1. **Breadcrumb:** The first line of every documentation file must be a + clickable breadcrumb trail with correct relative links. + - For `docs/README.md`: `[base](../README.md) > docs` + - For `docs/ai.md`: `[base](../README.md) > [docs](./README.md) > ai` + - For `docs/ai.prompting.md`: `[base](../../README.md) > [docs](../README.md) > [ai](./ai.md) > Prompting AI Agents` + 2. **`in-dev` Namespace:** Any documentation that is a work-in-progress or + not ready for general use should be placed in the `in-dev` namespace + (e.g., `docs/in-dev.my-draft.md`). Files in this namespace are + automatically excluded from all Tables of Contents. + 3. **Dual TOC Structure:** If you add a new, non-`in-dev` documentation file, + you **must** add a link to it in **two** places: + - The main Table of Contents in `docs/README.md`, under the appropriate + namespace heading. - The namespace-specific index file, `docs/.md`. - 4. If you are creating a new namespace, you must also create a `docs/.md` index file and link to it from the main `docs/README.md`. - **Verify Your Work:** After creating or modifying a file, use a read-only tool like `read_file` or `ls` to confirm your changes were applied correctly before marking a step as complete. diff --git a/docs/README.md b/docs/README.md index 1079751..1e4669a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,10 +1,8 @@ -# Documentation - -This directory contains the documentation for the `base` project. +[base](../README.md) > docs -- [The `base` Philosophy](./base.md) - An overview of the core principles and goals of this template. +# Documentation -[Guides](#guides) - [Development](#development) - [CI/CD](#cicd-workflows) - [Publishing](#publishing-your-project) - [Updating](#updating) - [Project Management](#project-management) - [Community](#community) - [AI](#ai) - [Documentation](#documentation-best-practices) +[Guides](#guides) - [Development](#development) - [CI/CD Workflows](#cicd-workflows) - [Publishing](#publishing) - [Updating](#updating) - [Project Management](#project-management) - [Community](#community) - [AI](#ai) - [Documentation Best Practices](#documentation-best-practices) ## Guides @@ -27,12 +25,12 @@ This directory contains the documentation for the `base` project. - [**Secrets Management**](./workflows.secrets-management.md) - Best practices for managing secrets in GitHub Actions. - [**Workflow Scheduling**](./workflows.scheduling.md) - Automating recurring tasks with cron. -## Publishing Your Project +## Publishing -- **[Publishing with Markdown](./publishing.markdown.md)** - This is the simplest way to get started. -- **[Advanced Publishing with HTML](./publishing.html.md)** - For those who need more control over their site's layout and appearance. -- **[Publishing with Magic Links](./publishing.magic-links.md)** - This guide explains a powerful feature for community-driven sites. -- **[GitHub Pages](./publishing.github-pages.md)** - This document provides more detail on how the underlying GitHub Pages service works. +- [Publishing with Markdown](./publishing.markdown.md) - The simplest way to get started with publishing content. +- [Advanced Publishing with HTML](./publishing.html.md) - For those who need more control over their site's layout and appearance. +- [Publishing with Magic Links](./publishing.magic-links.md) - A powerful feature for community-driven sites. +- [GitHub Pages](./publishing.github-pages.md) - More detail on how the underlying GitHub Pages service works. ## Updating diff --git a/docs/ai.agents-md.md b/docs/ai.agents-md.md index 231389a..fbf5e7d 100644 --- a/docs/ai.agents-md.md +++ b/docs/ai.agents-md.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [ai](./ai.md) > Guiding AI with AGENTS.md + # Guiding AI with `AGENTS.md` The `AGENTS.md` file is a special document within this repository designed to diff --git a/docs/ai.md b/docs/ai.md index 464256d..279ee4d 100644 --- a/docs/ai.md +++ b/docs/ai.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > ai + # AI This section contains documentation related to Artificial Intelligence. diff --git a/docs/ai.prompting.md b/docs/ai.prompting.md index 2f92eed..94c5c1a 100644 --- a/docs/ai.prompting.md +++ b/docs/ai.prompting.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [ai](./ai.md) > Prompting AI Agents + # Prompting AI Agents for `attogram/base` Projects When using AI agents to create or update a repository based on diff --git a/docs/base.md b/docs/base.md index 8ee6885..3de9ae0 100644 --- a/docs/base.md +++ b/docs/base.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > base + # The `base` Philosophy Welcome to `base`. diff --git a/docs/community.building.md b/docs/community.building.md index 33326f8..8a9bae0 100644 --- a/docs/community.building.md +++ b/docs/community.building.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [community](./community.md) > Community Building Guide + # Community Building Guide A thriving open-source project is built on a foundation of a healthy, diff --git a/docs/community.discussions.md b/docs/community.discussions.md index a959d03..616c547 100644 --- a/docs/community.discussions.md +++ b/docs/community.discussions.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [community](./community.md) > Using GitHub Discussions + # Using GitHub Discussions GitHub Discussions is a feature designed to be the community forum for your diff --git a/docs/community.issue-management.md b/docs/community.issue-management.md index 9d64642..e13147b 100644 --- a/docs/community.issue-management.md +++ b/docs/community.issue-management.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [community](./community.md) > Issue Management Guide + # Issue Management Guide Effective issue management is key to keeping your project organized and your diff --git a/docs/community.md b/docs/community.md index 078fef4..91bcee8 100644 --- a/docs/community.md +++ b/docs/community.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > community + # Community This section contains documentation related to community management. diff --git a/docs/community.wiki.md b/docs/community.wiki.md index efc7b88..ec89e79 100644 --- a/docs/community.wiki.md +++ b/docs/community.wiki.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [community](./community.md) > Using the GitHub Wiki + # Using the GitHub Wiki The GitHub Wiki is a powerful tool for hosting detailed, long-form documentation diff --git a/docs/deployment.md b/docs/deployment.md deleted file mode 100644 index 23d0cad..0000000 --- a/docs/deployment.md +++ /dev/null @@ -1,5 +0,0 @@ -# Deployment - -This section contains documentation related to deployment. - -- [Render Deployment](./deployment.render.md) - How to deploy the application to Render. diff --git a/docs/development.codespaces.md b/docs/development.codespaces.md index 11c196a..4c411b1 100644 --- a/docs/development.codespaces.md +++ b/docs/development.codespaces.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [development](./development.md) > GitHub Codespaces + # GitHub Codespaces This repository is configured to use diff --git a/docs/development.docker.md b/docs/development.docker.md index 71f83c8..72edc47 100644 --- a/docs/development.docker.md +++ b/docs/development.docker.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [development](./development.md) > Docker Environment + # Docker-based Development Environment This repository includes a Docker-based development environment to ensure a diff --git a/docs/development.md b/docs/development.md index 62a2d3f..454cbe1 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > development + # Development This section contains documentation related to development practices and environment setup. diff --git a/docs/development.package-json.md b/docs/development.package-json.md index a5990c9..4a842e8 100644 --- a/docs/development.package-json.md +++ b/docs/development.package-json.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [development](./development.md) > package.json Guide + # `package.json` and `package-lock.json` You may notice `package.json` and `package-lock.json` files in the root of diff --git a/docs/development.prettier.md b/docs/development.prettier.md index 4c668e6..bcbab77 100644 --- a/docs/development.prettier.md +++ b/docs/development.prettier.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [development](./development.md) > Using Prettier + # Prettier for Code Formatting [Prettier](https://prettier.io/) is an opinionated code formatter that enforces a consistent code style across the entire project. This repository is configured to use Prettier in two ways: automatically via a GitHub workflow and manually for local development. diff --git a/docs/documentation.best-practices.md b/docs/documentation.best-practices.md index c3397b5..c90f6d2 100644 --- a/docs/documentation.best-practices.md +++ b/docs/documentation.best-practices.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [documentation](./documentation.md) > Documentation Best Practices + # Documentation Best Practices Good documentation is one of the most important aspects of a successful diff --git a/docs/documentation.md b/docs/documentation.md index bc5034c..5830d71 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > documentation + # Documentation This section contains documentation about writing documentation. diff --git a/docs/guides.md b/docs/guides.md index eb8faae..af3794f 100644 --- a/docs/guides.md +++ b/docs/guides.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > guides + # Guides This section contains guides for using this project. diff --git a/docs/guides.software-project.md b/docs/guides.software-project.md index 749928b..f5aca8e 100644 --- a/docs/guides.software-project.md +++ b/docs/guides.software-project.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [guides](./guides.md) > Software Project Guide + # Use Case: A Starting Point for Your Software Project This repository is designed to be a robust foundation for a wide variety of diff --git a/docs/deployment.render.md b/docs/in-dev.render.md similarity index 94% rename from docs/deployment.render.md rename to docs/in-dev.render.md index 21b39f6..6ffb44e 100644 --- a/docs/deployment.render.md +++ b/docs/in-dev.render.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > in-dev > Render Deployment + # Deploying to Render.com > [!WARNING] diff --git a/docs/project.badges.md b/docs/project.badges.md index 02d0b4e..510f83e 100644 --- a/docs/project.badges.md +++ b/docs/project.badges.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [project](./project.md) > Repository Badges + # Badges Badges are a common way to display the status of your project in your diff --git a/docs/project.launch-checklist.md b/docs/project.launch-checklist.md index 2e5d240..80e6fc7 100644 --- a/docs/project.launch-checklist.md +++ b/docs/project.launch-checklist.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [project](./project.md) > Launch Checklist + # Project Launch Checklist Launching a new open-source project can be a daunting task. diff --git a/docs/project.licensing.md b/docs/project.licensing.md index 131d377..ee873c8 100644 --- a/docs/project.licensing.md +++ b/docs/project.licensing.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [project](./project.md) > Licensing Info + # Licensing Information This repository is distributed under the MIT License, the full text of which diff --git a/docs/project.md b/docs/project.md index 9983b08..ff62ca6 100644 --- a/docs/project.md +++ b/docs/project.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > project + # Project Management This section contains documentation related to project management. diff --git a/docs/project.security.md b/docs/project.security.md index 74a1dc7..31aada4 100644 --- a/docs/project.security.md +++ b/docs/project.security.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [project](./project.md) > Security Best Practices + # Security Best Practices for Maintainers As an open-source maintainer, you have a responsibility to ensure your diff --git a/docs/project.standard-files.md b/docs/project.standard-files.md index df4d5d8..682da33 100644 --- a/docs/project.standard-files.md +++ b/docs/project.standard-files.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [project](./project.md) > Standard Files + # Standard Repository Files This document explains the purpose of the standard, language-agnostic diff --git a/docs/project.template-repo.md b/docs/project.template-repo.md index 7beda21..6dd79a6 100644 --- a/docs/project.template-repo.md +++ b/docs/project.template-repo.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [project](./project.md) > Template Repo Guide + # Maintaining `base` as a Template Repository This document is for maintainers of the `base` repository. diff --git a/docs/project.versioning.md b/docs/project.versioning.md index 90f0969..38cabc6 100644 --- a/docs/project.versioning.md +++ b/docs/project.versioning.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [project](./project.md) > Versioning Guide + # Versioning and Release Management A well-defined versioning and release strategy is crucial for any professional diff --git a/docs/publishing.github-pages.md b/docs/publishing.github-pages.md index f3c6cde..3cf7b48 100644 --- a/docs/publishing.github-pages.md +++ b/docs/publishing.github-pages.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [publishing](./publishing.md) > GitHub Pages + # GitHub Pages Site This repository is configured to use [GitHub Pages](https://pages.github.com/) diff --git a/docs/publishing.html.md b/docs/publishing.html.md index 732d20c..362beb1 100644 --- a/docs/publishing.html.md +++ b/docs/publishing.html.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [publishing](./publishing.md) > Advanced Publishing with HTML + # Advanced Publishing: HTML, Previews, and More This guide covers the more advanced features of the publishing platform, diff --git a/docs/publishing.magic-links.md b/docs/publishing.magic-links.md index a610c22..d9a8194 100644 --- a/docs/publishing.magic-links.md +++ b/docs/publishing.magic-links.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [publishing](./publishing.md) > Publishing with Magic Links + # Publishing with Magic Links "Magic Links" are special URLs that can pre-fill a new file in a GitHub diff --git a/docs/publishing.markdown.md b/docs/publishing.markdown.md index b6b822d..0a992cc 100644 --- a/docs/publishing.markdown.md +++ b/docs/publishing.markdown.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [publishing](./publishing.md) > Publishing with Markdown + # Publishing with Markdown This repository is pre-configured to act as a simple, powerful, and free diff --git a/docs/publishing.md b/docs/publishing.md index ef640bd..b1d3c6a 100644 --- a/docs/publishing.md +++ b/docs/publishing.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > publishing + # Publishing Your Project This repository is pre-configured to act as a simple, powerful, and free diff --git a/docs/updating.adding-base-to-existing-repo.md b/docs/updating.adding-base-to-existing-repo.md index c62b948..c6a75da 100644 --- a/docs/updating.adding-base-to-existing-repo.md +++ b/docs/updating.adding-base-to-existing-repo.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [updating](./updating.md) > Adding base to an Existing Repo + # Merging `base` Into an Existing Repository This guide explains how to merge the `attogram/base` repository into your diff --git a/docs/updating.md b/docs/updating.md index 394d4b8..ac92bd6 100644 --- a/docs/updating.md +++ b/docs/updating.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > updating + # Updating This section contains documentation about updating the repository. diff --git a/docs/updating.syncing-your-repo-when-base-is-updated.md b/docs/updating.syncing-your-repo-when-base-is-updated.md index 6ee5a8c..636160a 100644 --- a/docs/updating.syncing-your-repo-when-base-is-updated.md +++ b/docs/updating.syncing-your-repo-when-base-is-updated.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [updating](./updating.md) > Syncing Your Repo When base is Updated + # Syncing Your Repo When `base` is Updated This guide explains how to sync your repository with the latest changes from the diff --git a/docs/workflows.ci.md b/docs/workflows.ci.md index da01955..8ea9dba 100644 --- a/docs/workflows.ci.md +++ b/docs/workflows.ci.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [workflows](./workflows.md) > CI Workflow + # CI Workflow The CI (Continuous Integration) workflow is defined in `.github/workflows/ci.yml`. diff --git a/docs/workflows.md b/docs/workflows.md index 1541c04..8413d5f 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > workflows + # CI/CD Workflows This repository includes several GitHub Actions workflows to automate various tasks. Each workflow is defined in a `.yml` file in the `.github/workflows` directory. diff --git a/docs/workflows.pages.md b/docs/workflows.pages.md index edb58bc..7969ad0 100644 --- a/docs/workflows.pages.md +++ b/docs/workflows.pages.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [workflows](./workflows.md) > GitHub Pages Deployment + # GitHub Pages Deployment Workflow The GitHub Pages deployment workflow is defined in `.github/workflows/pages.yml`. Its purpose is to build and deploy the repository's content as a GitHub Pages website. diff --git a/docs/workflows.prettier.md b/docs/workflows.prettier.md index 2d92715..dd58d7f 100644 --- a/docs/workflows.prettier.md +++ b/docs/workflows.prettier.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [workflows](./workflows.md) > Prettier Workflow + # Prettier Workflow The Prettier workflow, defined in `.github/workflows/prettier.yml`, automates code formatting for the entire repository. diff --git a/docs/workflows.release-on-tag.md b/docs/workflows.release-on-tag.md index 127c1e0..df2ce21 100644 --- a/docs/workflows.release-on-tag.md +++ b/docs/workflows.release-on-tag.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [workflows](./workflows.md) > Release on Tag + # Release on Tag Workflow The "Create Release" workflow, defined in `.github/workflows/release-on-tag.yml`, automates the process of creating a new GitHub release whenever a new tag is pushed to the repository. diff --git a/docs/workflows.scheduling.md b/docs/workflows.scheduling.md index f891436..71b3044 100644 --- a/docs/workflows.scheduling.md +++ b/docs/workflows.scheduling.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [workflows](./workflows.md) > Workflow Scheduling + # Scheduling Workflows with Cron GitHub Actions allows you to automate tasks on a schedule, similar to the diff --git a/docs/workflows.secrets-management.md b/docs/workflows.secrets-management.md index 531fd3e..76083fe 100644 --- a/docs/workflows.secrets-management.md +++ b/docs/workflows.secrets-management.md @@ -1,3 +1,5 @@ +[base](../README.md) > [docs](./README.md) > [workflows](./workflows.md) > Secrets Management + # Secrets Management in GitHub Actions Properly managing secrets like API keys, access tokens, and other credentials