diff --git a/README.md b/README.md index 7ca9137..e3cbe8c 100644 --- a/README.md +++ b/README.md @@ -11,4 +11,4 @@ Welcome to [base](./docs/base.md) - Your starting point for new GitHub repos - [Documentation](./docs/README.md) -- Repo: [https://github.com/attogram/base](https://github.com/attogram/base) +- Repo: [attogram/base](https://github.com/attogram/base) diff --git a/assets/logo1.svg b/assets/logo1.svg deleted file mode 100644 index 92662bf..0000000 --- a/assets/logo1.svg +++ /dev/null @@ -1,4 +0,0 @@ - - Logo 1: Solid Square - - diff --git a/assets/logo2.svg b/assets/logo2.svg deleted file mode 100644 index 5b5bbf7..0000000 --- a/assets/logo2.svg +++ /dev/null @@ -1,7 +0,0 @@ - - Logo 2: Nested Squares - - - - - diff --git a/assets/logo3.svg b/assets/logo3.svg deleted file mode 100644 index 4b6b615..0000000 --- a/assets/logo3.svg +++ /dev/null @@ -1,5 +0,0 @@ - - Logo 3: Stylized B - - - diff --git a/assets/logo4.svg b/assets/logo4.svg deleted file mode 100644 index 1b0461d..0000000 --- a/assets/logo4.svg +++ /dev/null @@ -1,7 +0,0 @@ - - Logo 4: Rocket Ship - - - - - diff --git a/assets/logo5.svg b/assets/logo5.svg deleted file mode 100644 index ab3de8b..0000000 --- a/assets/logo5.svg +++ /dev/null @@ -1,6 +0,0 @@ - - Logo 5: Stack of Blocks - - - - diff --git a/assets/logo_proposal_1.svg b/assets/logo_proposal_1.svg new file mode 100644 index 0000000..234c81c --- /dev/null +++ b/assets/logo_proposal_1.svg @@ -0,0 +1,5 @@ + + Logo Proposal 1: Simple Box + + base + diff --git a/assets/logo_proposal_10.svg b/assets/logo_proposal_10.svg new file mode 100644 index 0000000..03d25ae --- /dev/null +++ b/assets/logo_proposal_10.svg @@ -0,0 +1,7 @@ + + Logo Proposal 10: Abstract Boxes + + + + base + diff --git a/assets/logo_proposal_2.svg b/assets/logo_proposal_2.svg new file mode 100644 index 0000000..cf8f460 --- /dev/null +++ b/assets/logo_proposal_2.svg @@ -0,0 +1,5 @@ + + Logo Proposal 2: Outlined Box + + base + diff --git a/assets/logo_proposal_3.svg b/assets/logo_proposal_3.svg new file mode 100644 index 0000000..417691f --- /dev/null +++ b/assets/logo_proposal_3.svg @@ -0,0 +1,7 @@ + + Logo Proposal 3: Tilted Box + + + base + + diff --git a/assets/logo_proposal_4.svg b/assets/logo_proposal_4.svg new file mode 100644 index 0000000..3986c6d --- /dev/null +++ b/assets/logo_proposal_4.svg @@ -0,0 +1,7 @@ + + Logo Proposal 4: Overlapping Boxes + + ba + + se + diff --git a/assets/logo_proposal_5.svg b/assets/logo_proposal_5.svg new file mode 100644 index 0000000..4a2b6c9 --- /dev/null +++ b/assets/logo_proposal_5.svg @@ -0,0 +1,6 @@ + + Logo Proposal 5: Box with Shadow + + + base + diff --git a/assets/logo_proposal_6.svg b/assets/logo_proposal_6.svg new file mode 100644 index 0000000..e5ff390 --- /dev/null +++ b/assets/logo_proposal_6.svg @@ -0,0 +1,7 @@ + + Logo Proposal 6: Three-Stripe Box + + + + base + diff --git a/assets/logo_proposal_7.svg b/assets/logo_proposal_7.svg new file mode 100644 index 0000000..6b9abe2 --- /dev/null +++ b/assets/logo_proposal_7.svg @@ -0,0 +1,5 @@ + + Logo Proposal 7: Box as a Foundation + + base + diff --git a/assets/logo_proposal_8.svg b/assets/logo_proposal_8.svg new file mode 100644 index 0000000..8fcaaed --- /dev/null +++ b/assets/logo_proposal_8.svg @@ -0,0 +1,9 @@ + + Logo Proposal 8: Open Box + + + + + + base + diff --git a/assets/logo_proposal_9.svg b/assets/logo_proposal_9.svg new file mode 100644 index 0000000..3f20eb8 --- /dev/null +++ b/assets/logo_proposal_9.svg @@ -0,0 +1,6 @@ + + Logo Proposal 9: Circle in a Box + + + base + diff --git a/docs/README.md b/docs/README.md index bdebb9b..58eb1c2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,61 +2,61 @@ This directory contains the documentation for the `base` project. -- `[base.md](./base.md)` - The `base` Philosophy - An overview of the core principles and goals of this template. -- `[README.md](./README.md)` - Documentation Index - You are here. +- [The `base` Philosophy](./base.md) - An overview of the core principles and goals of this template. +- [Documentation Index](./README.md) - You are here. ## AI -- `[ai.agents-md.md](./ai.agents-md.md)` - Guiding AI with `AGENTS.md` - Using `AGENTS.md` to provide instructions to AI agents. -- `[ai.prompting.md](./ai.prompting.md)` - Prompting AI Agents - How to effectively prompt AI agents. +- [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. ## CI/CD -- `[cicd.secrets-management.md](./cicd.secrets-management.md)` - Secrets Management - Best practices for managing secrets in GitHub Actions. -- `[cicd.workflow-scheduling.md](./cicd.workflow-scheduling.md)` - Workflow Scheduling - Automating recurring tasks with cron. -- `[cicd.workflows.md](./cicd.workflows.md)` - GitHub Workflows - Explanation of the CI/CD workflows. +- [Secrets Management](./cicd.secrets-management.md) - Best practices for managing secrets in GitHub Actions. +- [Workflow Scheduling](./cicd.workflow-scheduling.md) - Automating recurring tasks with cron. +- [GitHub Workflows](./cicd.workflows.md) - Explanation of the CI/CD workflows. ## Community -- `[community.building.md](./community.building.md)` - Community Building Guide - Fostering a healthy and effective community. -- `[community.discussions.md](./community.discussions.md)` - Using GitHub Discussions - Leveraging Discussions for community conversations. -- `[community.issue-management.md](./community.issue-management.md)` - Issue Management Guide - Best practices for triaging issues. +- [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. ## Deployment -- `[deployment.render.md](./deployment.render.md)` - Deploying to Render.com - Instructions for deploying to Render.com. +- [Deploying to Render.com](./deployment.render.md) - Instructions for deploying to Render.com. ## Development -- `[development.codespaces.md](./development.codespaces.md)` - GitHub Codespaces - Using Codespaces for cloud-based development. -- `[development.docker.md](./development.docker.md)` - Docker Environment - Using the included Docker setup. -- `[development.merging-base.md](./development.merging-base.md)` - Merging `base` - Incorporating `base` into an existing project. -- `[development.package-json.md](./development.package-json.md)` - `package.json` Guide - Explanation of the `package.json` files. -- `[development.prettier.md](./development.prettier.md)` - Using Prettier - Guide to installing and using Prettier. -- `[development.prettier-workflow.md](./development.prettier-workflow.md)` - Prettier Workflow - Manually formatting code. +- [GitHub Codespaces](./development.codespaces.md) - Using Codespaces for cloud-based development. +- [Docker Environment](./development.docker.md) - Using the included Docker setup. +- [Merging `base`](./development.merging-base.md) - Incorporating `base` into an existing project. +- [`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. ## Documentation -- `[documentation.best-practices.md](./documentation.best-practices.md)` - Documentation Best Practices - How to write clear and effective documentation. +- [Documentation Best Practices](./documentation.best-practices.md) - How to write clear and effective documentation. ## Guides -- `[guides.software-project.md](./guides.software-project.md)` - Software Project Guide - Using this repo as a foundation for a software project. +- [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project. ## Project Management -- `[project.badges.md](./project.badges.md)` - Repository Badges - How to use and create repository badges. -- `[project.launch-checklist.md](./project.launch-checklist.md)` - Launch Checklist - A reusable checklist for project launches. -- `[project.licensing.md](./project.licensing.md)` - Licensing Info - Details on the MIT License. -- `[project.security.md](./project.security.md)` - Security Best Practices - Basic security practices for maintainers. -- `[project.standard-files.md](./project.standard-files.md)` - Standard Files - Explanation of standard repo files. -- `[project.template-repo.md](./project.template-repo.md)` - Template Repo Guide - Best practices for maintaining this template. -- `[project.versioning.md](./project.versioning.md)` - Versioning Guide - Professional release 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. ## Publishing -- `[publishing.md](./publishing.md)` - Publishing Overview - An overview of the different ways to publish content. -- `[publishing.markdown.md](./publishing.markdown.md)` - Publishing with Markdown - The simplest way to create pages. -- `[publishing.html.md](./publishing.html.md)` - Advanced Publishing with HTML - For more control over layout and style. -- `[publishing.magic-links.md](./publishing.magic-links.md)` - Publishing with Magic Links - Creating links that pre-fill new file content. -- `[publishing.github-pages.md](./publishing.github-pages.md)` - GitHub Pages - How the underlying publishing system works. +- [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. diff --git a/docs/base.md b/docs/base.md index bffcf8a..3783219 100644 --- a/docs/base.md +++ b/docs/base.md @@ -8,7 +8,7 @@ The development of this template is guided by a few core principles: 1. **Code-Independent:** The template should not be tied to a specific programming language. The goal is to provide a solid foundation of repository structure, CI/CD, and best practices that can be adapted to any language or framework. -2. **Well-Documented:** Every component, workflow, and configuration file is documented in the [`docs`](./) directory. The goal is to make the repository easy to understand and modify. +2. **Well-Documented:** Every component, workflow, and configuration file is documented in the [`docs`](./) directory. The goal is to make the repository easy to understand and modify. See the [documentation index](./README.md) for a complete list of documents. 3. **Guidance Over Prescription:** The template provides sensible defaults and placeholder files that guide the user on how to create their own project-specific content, such as contributing guidelines or a license. diff --git a/docs/community.discussions.md b/docs/community.discussions.md index fc25b4d..76327f8 100644 --- a/docs/community.discussions.md +++ b/docs/community.discussions.md @@ -27,7 +27,7 @@ By directing non-actionable conversations to Discussions, you prevent your issue - **Ideas:** For proposing and debating new features. - **Show and Tell:** For community members to share what they've built with your project. -See: https://docs.github.com/en/discussions/managing-discussions-for-your-community/managing-categories-for-discussions +See: [Managing categories for discussions](https://docs.github.com/en/discussions/managing-discussions-for-your-community/managing-categories-for-discussions) ## Best Practices for Maintainers diff --git a/docs/community.wiki.md b/docs/community.wiki.md new file mode 100644 index 0000000..e7d9809 --- /dev/null +++ b/docs/community.wiki.md @@ -0,0 +1,37 @@ +# Using the GitHub Wiki + +The GitHub Wiki is a powerful tool for hosting detailed, long-form documentation for your project. Unlike your repository's `README.md` file, which is meant to be a quick introduction, the wiki provides a dedicated space for comprehensive guides, tutorials, and reference material. + +## `README.md` vs. Wiki: What's the Difference? + +Understanding when to use your `README.md` and when to use the wiki is key to keeping your project's documentation organized and accessible. + +- **`README.md`** is the front door to your project. It should be concise and provide a high-level overview, installation instructions, and a quick start guide. It's the first thing most visitors will see. + +- **The Wiki** is the library for your project. It's the place for "deep dive" content that doesn't fit in the README. + - **Use for:** In-depth tutorials, API references, design documents, project history, and FAQs. + - **Example:** A detailed guide on "Advanced Configuration Options" or a "Contributor's Guide to the Codebase." + +By moving detailed documentation to the wiki, you keep your `README.md` clean and focused, while providing a structured and searchable home for your project's knowledge base. + +## How to Use the Wiki + +1. **Enable the Wiki:** In your repository settings, under the "Features" section, check the box for "Wiki." + +2. **Create a Home Page:** Every wiki starts with a `Home.md` page. This page should serve as a table of contents, with links to all the other pages in your wiki. + +3. **Add and Edit Pages:** You can add new pages and edit existing ones directly in the GitHub web interface. The wiki uses Markdown, just like the rest of GitHub. + +4. **Link Pages Together:** Create links between your wiki pages to build a cohesive and navigable documentation site. You can link to another wiki page using the syntax `[[Page Name]]`. + +## Best Practices for Maintainers + +1. **Keep it Organized:** Use the `Home.md` page as a table of contents. Group related pages together with clear and consistent naming. + +2. **Encourage Contributions:** By default, anyone with push access to your repository can edit the wiki. Encourage your community to contribute to the documentation. + +3. **Review and Curate:** Periodically review the content of your wiki to ensure it is up-to-date and accurate. Remove outdated information and refactor pages as your project evolves. + +4. **Link to the Wiki from your `README.md`:** Add a link to your wiki from your project's `README.md` file so that visitors can easily find your detailed documentation. + +By leveraging the GitHub Wiki, you can build a comprehensive and collaborative documentation site that will help your users and contributors get the most out of your project.