diff --git a/AGENTS.md b/AGENTS.md index eeacb65..204465c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,9 +49,10 @@ repository: - [`SECURITY.md`](./.github/SECURITY.md): A template for the user's security policy. -- **[`docs/`](./docs/)**: Contains all documentation for the project. - Each major feature or component has its own corresponding `.md` file in this - directory. +- **[`docs/`](./docs/)**: Contains all documentation for the project. The documentation is organized into namespaces. + - **`docs/README.md`**: The main entry point for documentation, which serves as a Table of Contents. + - **`docs/.md`**: Each namespace has a top-level index file (e.g., `docs/ai.md`) that provides an overview and links to all the sub-pages within that namespace. + - **`docs/..md`**: Individual documentation pages for specific topics within a namespace. - **[`docker/`](./docker/)**: Contains the development environment. - [`Dockerfile`](./docker/Dockerfile): Builds a generic Ubuntu + NGINX @@ -88,7 +89,13 @@ repository: - **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. + 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. + - 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 c99295a..1079751 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,24 +3,12 @@ This directory contains the documentation for the `base` project. - [The `base` Philosophy](./base.md) - An overview of the core principles and goals of this template. -- [Documentation Index](./README.md) - You are here. -## AI - -- [Guiding AI with `AGENTS.md`](./ai.agents-md.md) - Using `AGENTS.md` to provide instructions to AI agents. -- [Prompting AI Agents](./ai.prompting.md) - How to effectively prompt AI agents. +[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) -## CI/CD - -- [Secrets Management](./workflows.secrets-management.md) - Best practices for managing secrets in GitHub Actions. -- [Workflow Scheduling](./workflows.scheduling.md) - Automating recurring tasks with cron. -- [GitHub Workflows](./workflows.md) - Explanation of the CI/CD workflows. - -## Community +## Guides -- [Community Building Guide](./community.building.md) - Fostering a healthy and effective community. -- [Using GitHub Discussions](./community.discussions.md) - Leveraging Discussions for community conversations. -- [Issue Management Guide](./community.issue-management.md) - Best practices for triaging issues. +- [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project. ## Development @@ -30,13 +18,21 @@ This directory contains the documentation for the `base` project. - [Using Prettier](./development.prettier.md) - Guide to installing and using Prettier. - [Prettier Workflow](./development.prettier-workflow.md) - Manually formatting code. -## Documentation +## CI/CD Workflows -- [Documentation Best Practices](./documentation.best-practices.md) - How to write clear and effective documentation. +- [**CI Workflow**](./workflows.ci.md) (`ci.yml`) - Ensures code quality by running linting checks on every push and pull request to the `main` branch. +- [**GitHub Pages Deployment**](./workflows.pages.md) (`pages.yml`) - Builds and deploys the repository's content as a GitHub Pages website. +- [**Prettier Workflow**](./workflows.prettier.md) (`prettier.yml`) - Automatically formats the code in the repository using Prettier and commits the changes. +- [**Release on Tag**](./workflows.release-on-tag.md) (`release-on-tag.yml`) - Automates the creation of GitHub Releases when a new version tag is pushed. +- [**Secrets Management**](./workflows.secrets-management.md) - Best practices for managing secrets in GitHub Actions. +- [**Workflow Scheduling**](./workflows.scheduling.md) - Automating recurring tasks with cron. -## Guides +## Publishing Your Project -- [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project. +- **[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. ## Updating @@ -53,10 +49,17 @@ This directory contains the documentation for the `base` project. - [Template Repo Guide](./project.template-repo.md) - Best practices for maintaining this template. - [Versioning Guide](./project.versioning.md) - Professional release management. -## Publishing +## Community -- [Publishing Overview](./publishing.md) - An overview of the different ways to publish content. -- [Publishing with Markdown](./publishing.markdown.md) - The simplest way to create pages. -- [Advanced Publishing with HTML](./publishing.html.md) - For more control over layout and style. -- [Publishing with Magic Links](./publishing.magic-links.md) - Creating links that pre-fill new file content. -- [GitHub Pages](./publishing.github-pages.md) - How the underlying publishing system works. +- [Community Building Guide](./community.building.md) - Fostering a healthy and effective community. +- [Using GitHub Discussions](./community.discussions.md) - Leveraging Discussions for community conversations. +- [Issue Management Guide](./community.issue-management.md) - Best practices for triaging issues. + +## AI + +- [Guiding AI with `AGENTS.md`](./ai.agents-md.md) - Using `AGENTS.md` to provide instructions to AI agents. +- [Prompting AI Agents](./ai.prompting.md) - How to effectively prompt AI agents. + +## Documentation Best Practices + +- [Documentation Best Practices](./documentation.best-practices.md) - How to write clear and effective documentation. diff --git a/docs/ai.md b/docs/ai.md new file mode 100644 index 0000000..464256d --- /dev/null +++ b/docs/ai.md @@ -0,0 +1,6 @@ +# AI + +This section contains documentation related to Artificial Intelligence. + +- [Guiding AI with `AGENTS.md`](./ai.agents-md.md) - Using `AGENTS.md` to provide instructions to AI agents. +- [Prompting AI Agents](./ai.prompting.md) - How to effectively prompt AI agents. diff --git a/docs/community.md b/docs/community.md new file mode 100644 index 0000000..078fef4 --- /dev/null +++ b/docs/community.md @@ -0,0 +1,7 @@ +# Community + +This section contains documentation related to community management. + +- [Community Building Guide](./community.building.md) - Fostering a healthy and effective community. +- [Using GitHub Discussions](./community.discussions.md) - Leveraging Discussions for community conversations. +- [Issue Management Guide](./community.issue-management.md) - Best practices for triaging issues. diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..23d0cad --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,5 @@ +# 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.md b/docs/development.md new file mode 100644 index 0000000..62a2d3f --- /dev/null +++ b/docs/development.md @@ -0,0 +1,9 @@ +# Development + +This section contains documentation related to development practices and environment setup. + +- [GitHub Codespaces](./development.codespaces.md) - Using Codespaces for cloud-based development. +- [Docker Environment](./development.docker.md) - Using the included Docker setup. +- [`package.json` Guide](./development.package-json.md) - Explanation of the `package.json` files. +- [Using Prettier](./development.prettier.md) - Guide to installing and using Prettier. +- [Prettier Workflow](./development.prettier-workflow.md) - Manually formatting code. diff --git a/docs/documentation.md b/docs/documentation.md new file mode 100644 index 0000000..bc5034c --- /dev/null +++ b/docs/documentation.md @@ -0,0 +1,5 @@ +# Documentation + +This section contains documentation about writing documentation. + +- [Documentation Best Practices](./documentation.best-practices.md) - How to write clear and effective documentation. diff --git a/docs/guides.md b/docs/guides.md new file mode 100644 index 0000000..eb8faae --- /dev/null +++ b/docs/guides.md @@ -0,0 +1,5 @@ +# Guides + +This section contains guides for using this project. + +- [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project. diff --git a/docs/project.md b/docs/project.md new file mode 100644 index 0000000..9983b08 --- /dev/null +++ b/docs/project.md @@ -0,0 +1,11 @@ +# Project Management + +This section contains documentation related to project management. + +- [Repository Badges](./project.badges.md) - How to use and create repository badges. +- [Launch Checklist](./project.launch-checklist.md) - A reusable checklist for project launches. +- [Licensing Info](./project.licensing.md) - Details on the MIT License. +- [Security Best Practices](./project.security.md) - Basic security practices for maintainers. +- [Standard Files](./project.standard-files.md) - Explanation of standard repo files. +- [Template Repo Guide](./project.template-repo.md) - Best practices for maintaining this template. +- [Versioning Guide](./project.versioning.md) - Professional release management. diff --git a/docs/updating.md b/docs/updating.md new file mode 100644 index 0000000..394d4b8 --- /dev/null +++ b/docs/updating.md @@ -0,0 +1,6 @@ +# Updating + +This section contains documentation about updating the repository. + +- [Adding `base` to an Existing Repo](./updating.adding-base-to-existing-repo.md) - How to merge `base` into a project that was not created from the template. +- [Syncing When `base` is Updated](./updating.syncing-your-repo-when-base-is-updated.md) - How to get the latest changes from `base` after you have already merged it. diff --git a/docs/workflows.md b/docs/workflows.md index 8d5d451..1541c04 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -6,14 +6,9 @@ Below is an overview of the available workflows. For more detailed information a ## Workflow Index -- [**CI Workflow**](./workflows.ci.md) (`ci.yml`) -- Ensures code quality by running linting checks on every push and pull request to the `main` branch. - -- [**GitHub Pages Deployment**](./workflows.pages.md) (`pages.yml`) -- Builds and deploys the repository's content as a GitHub Pages website. - -- [**Prettier Workflow**](./workflows.prettier.md) (`prettier.yml`) -- Automatically formats the code in the repository using Prettier and commits the changes. - -- [**Release on Tag**](./workflows.release-on-tag.md) (`release-on-tag.yml`) -- Automates the creation of GitHub Releases when a new version tag is pushed. +- [**CI Workflow**](./workflows.ci.md) (`ci.yml`) - Ensures code quality by running linting checks on every push and pull request to the `main` branch. +- [**GitHub Pages Deployment**](./workflows.pages.md) (`pages.yml`) - Builds and deploys the repository's content as a GitHub Pages website. +- [**Prettier Workflow**](./workflows.prettier.md) (`prettier.yml`) - Automatically formats the code in the repository using Prettier and commits the changes. +- [**Release on Tag**](./workflows.release-on-tag.md) (`release-on-tag.yml`) - Automates the creation of GitHub Releases when a new version tag is pushed. +- [**Secrets Management**](./workflows.secrets-management.md) - Best practices for managing secrets in GitHub Actions. +- [**Workflow Scheduling**](./workflows.scheduling.md) - Automating recurring tasks with cron.