attogram · attogram · Sep 3, 2025 · Sep 3, 2025 · Sep 3, 2025 · Sep 3, 2025
diff --git a/assets/logo1.svg b/assets/logo1.svg
diff --git a/assets/logo2.svg b/assets/logo2.svg
diff --git a/assets/logo3.svg b/assets/logo3.svg
diff --git a/assets/logo4.svg b/assets/logo4.svg
diff --git a/assets/logo5.svg b/assets/logo5.svg
diff --git a/docs/README.md b/docs/README.md
@@ -2,30 +2,61 @@
 
 This directory contains the documentation for the `base` project.
 
-- **[The `base` Philosophy](./base.md)**: An overview of the core principles and goals behind this template repository.
-- **[Docker-based Development Environment](./docker.md)**: Instructions on how to use the included Docker setup for a consistent development environment.
-- **[GitHub Codespaces](./github-codespaces.md)**: A guide to using GitHub Codespaces for a cloud-based development experience.
-- **[GitHub Pages Site](./github-pages.md)**: Information on how the project's documentation is automatically built and deployed as a website.
-- **[Use Case: A Publishing Platform](./use-case-publishing.md)**: A detailed guide on using this repository as a platform to create and publish your own website.
-- **[Use Case: A Software Project](./use-case-software-project.md)**: A guide to using this repository as a foundation for your own software project.
-- **[Prompting AI Agents](./prompting-ai-agents.md)**: A guide on how to effectively prompt AI agents when working on `base`-based projects.
-- **[Guiding AI with `AGENTS.md`](./agents-md-guide.md)**: An explanation of how to use the `AGENTS.md` file to provide persistent instructions to AI agents.
-- **[The `package.json` files](./package-json-guide.md)**: An explanation of the `package.json` and `package-lock.json` files used for development tooling.
-- **[GitHub Workflows](./github-workflows.md)**: An explanation of the CI/CD workflows for linting, testing, and releasing.
-- **[Manually Formatting Code with the Prettier Workflow](./prettier-workflow.md)**: A guide to using the manually-triggered workflow to format the codebase.
-- **[Licensing Information](./licensing.md)**: Details on the MIT License and how to properly attribute copyright.
-- **[Deploying to Render.com](./render.md)**: Instructions for deploying the project to the Render.com platform.
-- **[Merging `base` Into an Existing Repository](./merging-base.md)**: A guide on how to incorporate `base` into an existing project.
-- **[Standard Repository Files](./standard-files.md)**: An explanation of the standard configuration files like `.gitignore`, `.editorconfig`, and `.gitattributes`.
-- **[Using Prettier](./prettier.md)**: A guide to installing and using Prettier for code formatting.
-- **[Repository Badges](./badges.md)**: An explanation of how to use and create repository badges.
-- **[Maintaining `base` as a Template Repository](./template-repo.md)**: A guide for maintainers of this template, outlining best practices and administrative steps.
-- **[Versioning and Release Management](./versioning-guide.md)**: A guide to professional release management using Semantic Versioning and GitHub's automated release notes feature.
-- **[Community Building Guide](./community-building-guide.md)**: Best-practice advice on how to foster a healthy, welcoming, and effective community around a new open-source project.
-- **[Project Launch Checklist](./launch-checklist.md)**: A reusable checklist for ensuring a smooth and successful project launch.
-- **[Secrets Management in GitHub Actions](./secrets-management.md)**: A guide on the best practice of using GitHub Actions secrets to manage sensitive credentials.
-- **[Scheduling Workflows with Cron](./workflow-scheduling.md)**: A tutorial on how to use cron scheduling within GitHub Actions to automate recurring tasks.
-- **[Issue Management Guide](./issue-management-guide.md)**: A guide to best practices for triaging bug reports and feature requests using GitHub Issues.
-- **[Documentation Best Practices](./documentation-best-practices.md)**: A tutorial on the art of writing clear and effective documentation.
-- **[Using GitHub Discussions](./using-github-discussions.md)**: A guide on how to leverage GitHub Discussions for community conversations.
-- **[Security Best Practices for Maintainers](./security-best-practices.md)**: A guide covering basic security practices for open-source maintainers.
+- `[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.
+
+## 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.
+
+## 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.
+
+## 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.
+
+## Deployment
+
+- `[deployment.render.md](./deployment.render.md)` - Deploying to Render.com - 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.
+
+## Documentation
+
+- `[documentation.best-practices.md](./documentation.best-practices.md)` - Documentation Best Practices - 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.
+
+## 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.
+
+## 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.
diff --git a/docs/agents-md-guide.md → docs/ai.agents-md.md b/docs/agents-md-guide.md → docs/ai.agents-md.md
diff --git a/docs/prompting-ai-agents.md → docs/ai.prompting.md b/docs/prompting-ai-agents.md → docs/ai.prompting.md
diff --git a/docs/secrets-management.md → docs/cicd.secrets-management.md b/docs/secrets-management.md → docs/cicd.secrets-management.md
diff --git a/docs/workflow-scheduling.md → docs/cicd.workflow-scheduling.md b/docs/workflow-scheduling.md → docs/cicd.workflow-scheduling.md
diff --git a/docs/github-workflows.md → docs/cicd.workflows.md b/docs/github-workflows.md → docs/cicd.workflows.md
diff --git a/docs/community-building-guide.md → docs/community.building.md b/docs/community-building-guide.md → docs/community.building.md
diff --git a/docs/using-github-discussions.md → docs/community.discussions.md b/docs/using-github-discussions.md → docs/community.discussions.md
diff --git a/docs/issue-management-guide.md → docs/community.issue-management.md b/docs/issue-management-guide.md → docs/community.issue-management.md
diff --git a/docs/render.md → docs/deployment.render.md b/docs/render.md → docs/deployment.render.md
diff --git a/docs/github-codespaces.md → docs/development.codespaces.md b/docs/github-codespaces.md → docs/development.codespaces.md
diff --git a/docs/docker.md → docs/development.docker.md b/docs/docker.md → docs/development.docker.md
diff --git a/docs/merging-base.md → docs/development.merging-base.md b/docs/merging-base.md → docs/development.merging-base.md
diff --git a/docs/package-json-guide.md → docs/development.package-json.md b/docs/package-json-guide.md → docs/development.package-json.md
diff --git a/docs/prettier-workflow.md → docs/development.prettier-workflow.md b/docs/prettier-workflow.md → docs/development.prettier-workflow.md
diff --git a/docs/prettier.md → docs/development.prettier.md b/docs/prettier.md → docs/development.prettier.md
diff --git a/docs/documentation-best-practices.md → docs/documentation.best-practices.md b/docs/documentation-best-practices.md → docs/documentation.best-practices.md
diff --git a/docs/use-case-software-project.md → docs/guides.software-project.md b/docs/use-case-software-project.md → docs/guides.software-project.md
diff --git a/docs/badges.md → docs/project.badges.md b/docs/badges.md → docs/project.badges.md
diff --git a/docs/launch-checklist.md → docs/project.launch-checklist.md b/docs/launch-checklist.md → docs/project.launch-checklist.md
diff --git a/docs/licensing.md → docs/project.licensing.md b/docs/licensing.md → docs/project.licensing.md
diff --git a/docs/security-best-practices.md → docs/project.security.md b/docs/security-best-practices.md → docs/project.security.md
diff --git a/docs/standard-files.md → docs/project.standard-files.md b/docs/standard-files.md → docs/project.standard-files.md
diff --git a/docs/template-repo.md → docs/project.template-repo.md b/docs/template-repo.md → docs/project.template-repo.md
diff --git a/docs/versioning-guide.md → docs/project.versioning.md b/docs/versioning-guide.md → docs/project.versioning.md
diff --git a/docs/github-pages.md → docs/publishing.github-pages.md b/docs/github-pages.md → docs/publishing.github-pages.md
diff --git a/docs/publishing.html.md b/docs/publishing.html.md
@@ -0,0 +1,99 @@
+# Advanced Publishing: HTML, Previews, and More
+
+This guide covers the more advanced features of the publishing platform, including using HTML, previewing your site locally, and understanding the platform's limitations.
+
+## Using HTML for More Control
+
+While Markdown is easy to use, you can also use standard HTML (`.html`) files for your pages. This is useful for complex layouts that require specific HTML structures or CSS classes.
+
+You can create new `.html` files or add existing ones to the repository, and they will be published as pages on your site.
+
+While most HTML tags are stripped for security, GitHub Pages allows a "whitelist" of safe tags for advanced formatting.
+
+A great example is creating a collapsible section using `<details>` and `<summary>`.
+
+```html
+<details>
+  <summary>Click here to see the details!</summary>
+
+  This content is hidden until you click the summary. You can put any Markdown
+  content in here, including lists, code blocks, or images.
+</details>
+```
+
+Other useful HTML tags that are generally allowed include `<sub>` for <sub>subscript</sub>, `<sup>` for <sup>superscript</sup>, and `<kbd>` for styling keyboard inputs like <kbd>Ctrl</kbd>+<kbd>C</kbd>.
+
+## Advanced Theming
+
+### Using Other Themes
+
+You are not limited to the themes supported by default. Using the `remote_theme` option in `_config.yml`, you can use almost any public Jekyll theme hosted on GitHub.
+
+```yaml
+# remote_theme: owner/repository-name
+remote_theme: jekyll/minima
+```
+
+### Customizing a Theme's CSS
+
+If you want to add your own custom styles without creating a whole new theme, you can override the theme's CSS.
+
+1.  Create a file named `/assets/css/style.scss`.
+2.  Add the following lines to the top of the file. This imports the theme's default stylesheet.
+
+    ```scss
+    ---
+    ---
+
+    @import "{{ site.theme }}";
+    ```
+
+3.  Below the `@import` line, you can add any custom CSS you want.
+
+---
+
+## Understanding the Limitations
+
+GitHub Pages is a powerful tool, but it's important to understand its limitations.
+
+- **Static Sites Only:** This is the most important limitation. GitHub Pages cannot run server-side code (like PHP, Python, or a database). It can only serve static files: HTML, CSS, JavaScript, images, etc. This means you cannot have features like a user login system, a shopping cart, or a server-side contact form.
+
+- **Usage Limits:** For repositories on the free plan, GitHub Pages has some soft limits:
+  - **Size:** Your repository should ideally stay under 1GB.
+  - **Bandwidth:** Your site has a soft limit of 100GB of bandwidth per month.
+  - **Builds:** Your site will be rebuilt up to 10 times per hour. Pushing many small commits in a short period might cause some builds to be skipped.
+
+- **No Custom Jekyll Plugins:** GitHub Pages only supports a specific list of Jekyll plugins. You cannot use custom or third-party plugins that are not on [this list](https://pages.github.com/versions/).
+
+- **Site Visibility:** If your repository is public, your GitHub Pages site will be public. If your repository is private, your site will also be public unless you have a paid GitHub plan (Pro, Team, or Enterprise).
+
+---
+
+## Advanced Topics
+
+### Previewing Your Site Locally
+
+The default workflow is to push changes and wait for GitHub to publish them. For larger changes, you may want to preview your site on your own computer before publishing.
+
+This requires installing Ruby and Jekyll. While the setup can be technical, the benefit is that you can run a local web server that behaves exactly like GitHub Pages and see your changes instantly at `http://localhost:4000`.
+
+To learn how to do this, follow the official guide from GitHub:
+
+- **[Testing your GitHub Pages site locally with Jekyll](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll)**
+
+### Creating a Navigation Menu
+
+Many themes allow you to create a persistent navigation menu at the top of your site. The implementation details depend on the theme, but it is often configured in the `_config.yml` file.
+
+For example, the popular "Minima" theme looks for a `header_pages` array in your `_config.yml`:
+
+```yaml
+# In _config.yml
+header_pages:
+  - about.md
+  - contact.md
+```
+
+The default `primer` theme does not support this feature out-of-the-box. To add a navigation menu, you will need to switch to a different theme or add your own custom HTML layout.
+
+**Always check the documentation for your chosen theme** to see what navigation features it supports and how to configure them.
diff --git a/docs/publishing.magic-links.md b/docs/publishing.magic-links.md
@@ -0,0 +1,62 @@
+# Publishing with Magic Links
+
+"Magic Links" are special URLs that can pre-fill a new file in a GitHub repository with template content. This is a powerful way to encourage community contributions by making it easy for users to submit content in a structured format, such as a bug report, a testimonial, or a new blog post.
+
+## How They Work
+
+The link is a standard URL used to create a new file on GitHub, but it is enhanced with query parameters to specify a filename and pre-fill its content.
+
+Here is a generic example of what the Markdown for a magic link might look like:
+
+```markdown
+[<kbd>Click Here to Add a New Item</kbd>](https://github.com/{OWNER}/{REPO}/new/{BRANCH}/?filename={PATH_TO_FILE}&value={URL_ENCODED_CONTENT})
+```
+
+### Key Parameters
+
+- `filename`: This specifies the directory and name of the file to be created. You can use placeholders to guide users, for example: `_posts/YYYY-MM-DD-your-title.md`. This encourages good file naming conventions.
+- `value`: This contains the URL-encoded content that will pre-fill the new file.
+
+## Deconstructing the `value` Parameter
+
+The `value` parameter is the core of the magic link. It's your template, but URL-encoded.
+
+Here is an example of a decoded template for a simple blog post:
+
+```yaml
+---
+layout: post
+title: "[YOUR TITLE HERE]"
+date: YYYY-MM-DD
+description: "[A one-sentence summary of your post]"
+author: "[Your Name or GitHub Username]"
+---
+
+[YOUR FULL CONTENT HERE. Write as much as you want!]
+
+**How to add images:**
+1. After creating this file, drag & drop your images into this folder.
+2. Link to them with `![Image description](./your-image-name.png)`
+```
+
+This example uses a standard Jekyll post format with YAML front matter. The placeholders guide the user on what to fill in.
+
+## How to Create Your Own Magic Link
+
+1.  **Write Your Template Content:** In a text editor, write the exact content you want to pre-fill for the user. Use clear placeholders like `[REPLACE THIS]` to indicate where they should add their own information.
+
+2.  **URL-Encode the Content:** Your template content must be URL-encoded to be safely included in the link. This process converts special characters (like spaces, newlines, and symbols) into a format that can be transmitted over the internet. There are many free online tools available for URL encoding. Simply paste your template content into one of these tools to get the encoded version.
+
+3.  **Construct the Final URL:** Assemble the link by combining the base URL and your parameters.
+    - **Base URL:** `https://github.com/{OWNER}/{REPO}/new/{BRANCH}/`
+      - Replace `{OWNER}`, `{REPO}`, and `{BRANCH}` with your repository's information.
+    - **Filename:** `?filename=path/to/your/new-file.md`
+      - Define the path and name for the new file.
+    - **Value:** `&value={YOUR_ENCODED_CONTENT}`
+      - Paste your URL-encoded template content here.
+
+4.  **Create the Markdown Link:** For easy use, embed your final URL into a Markdown link. Using `<kbd>` tags can make the link appear more like a button, which can improve user experience.
+
+    ```markdown
+    [<kbd>Click Here to Contribute</kbd>](YOUR_FINAL_URL)
+    ```