docs: finish Concepts section

Author: softwareentrepreneer

afterpython/doc/concepts.md

@@ -1,43 +1,53 @@
-# Concepts
-
-::::{aside}
-:::{glossary}
-MyST Markdown
-: MyST Markdown is a superset of Markdown that adds support for Sphinx-style directives and roles.
-:::
-
-:::{glossary}
-Jupyter Notebook
-: Jupyter Notebook is an interactive computational environment that allows you to write and execute code in a notebook format.
-:::
-
-:::{glossary}
-pre-commit
-: pre-commit is a tool that allows you to run checks on your code before you commit it.
-:::
-
-:::{glossary}
-GitHub Actions
-: GitHub Actions is a CI/CD platform that allows you to automate your workflow.
-:::
-::::
-
-
-## How It Works
-`afterpython` uses [MyST Document Engine] under the hood so you can write content in [MyST Markdown] and [Jupyter Notebook], then builds a project website using a [template] to display all your content in an organized way.
+[mystmd]: https://mystmd.org
+[commitizen]: https://github.com/commitizen-tools/commitizen
+[pre-commit]: https://github.com/pre-commit/pre-commit
+[ruff]: https://github.com/astral-sh/ruff
 
+# Concepts
 
 ## afterpython/ Folder
-aim to store everything python project related
-provide a structured way
-
-
-## Structure / Content Types
-explain each of their definitions
-- content
-    - doc
-    - blog
-    - tutorial
-    - example
-    - guide
--
+The `afterpython/` folder serves as a centralized location for both your project website content and maintenance tool configurations. It contains:
+
+**Content directories:**
+- `afterpython/doc/` - Documentation
+- `afterpython/blog/` - Blog posts
+- `afterpython/tutorial/` - Tutorials
+- `afterpython/example/` - Examples
+- `afterpython/guide/` - How-to Guides
+
+**Configuration files:**
+- `cz.toml` for [commitizen]
+- `ruff.toml` for [ruff]
+- `.pre-commit-config.yaml` for [pre-commit]
+- `authors.yml` for [mystmd]
+- `afterpython.toml` for `afterpython` itself
+
+**Purpose:**
+
+This structure serves two goals:
+
+1. **Declutter the root directory** - Keeps maintenance-related configuration files separate from package code, making the project structure cleaner
+2. **Provide sane defaults** - Comes pre-configured with sensible defaults for common maintenance tools like [commitizen], [pre-commit], and [ruff], so you can start using them immediately
+
+
+---
+## afterpython.toml
+`afterpython.toml` is a configuration file for `afterpython`. Think of it as an extension of `pyproject.toml`, storing extra information about your project such as company name, company URL, project website URL, etc. Currently it only supports the following fields:
+
+```toml
+[company]
+name = "Your Company Name"
+url = "https://your-company.com"
+
+[website]
+url = "https://your-project-website.com"
+```
+
+---
+## Content Types
+- **Documentation** (`afterpython/doc/`) - Conceptual explanations on how the project works
+- **Blog** (`afterpython/blog/`) - Project updates, announcements, and release notes
+- **Tutorials** (`afterpython/tutorial/`) - Step-by-step learning guides
+- **Examples** (`afterpython/example/`) - Real-world code examples/snippets
+- **Guides** (`afterpython/guide/`) - Task-oriented how-to instructions
+- **API Reference** (`afterpython/reference/`) - Auto-generated API documentation from docstrings

afterpython/doc/myst.yml

@@ -35,7 +35,6 @@ project:
   toc:
   - file: overview.md
   - file: quickstart.md
-  - file: walkthrough.md
   - file: concepts.md
   - file: myst.md
   - file: project_website.md

afterpython/doc/overview.md

@@ -24,9 +24,9 @@
 - Write content directly in [MyST Markdown] or [Jupyter Notebook]
 - Go from writing to website deployment in minutes — no need to learn any of the underlying tools
 - Centralize all your content in a modern, unified project website — from documentation to blog posts
-- (Work In Progress) Export content as PDF — for example, combine all blog posts into a single PDF file
-- (Work In Progress) **⚡ Full-text search** across **ALL** your content in your website — docs, blogs, tutorials, everything
-- (Work In Progress) **🤖 Embedded AI Chatbot** that answers questions directly using an in-browser LLM — at no cost
+- 🚧 Export content as PDF — for example, combine all blog posts into a single PDF file
+- 🚧 **⚡ Full-text search** across **ALL** your content in your website — docs, blogs, tutorials, everything
+- 🚧 **🤖 Embedded AI Chatbot** that answers questions directly using an in-browser LLM — at no cost
 
 ---
 ## Tech Stack

afterpython/doc/project_website.md

@@ -58,10 +58,15 @@ When updates are available, run `ap update website`, which will update `afterpyt
 ## Customization and Styling
 Since all the code is pulled from [project-website-template] to `afterpython/_website/`, you can customize the project website by modifying the code in `afterpython/_website/src/`.
 
+
+### Landing Page
 For example, to change the landing page, which by default displays the `README.md`, you can modify the code in `afterpython/_website/src/routes/+page.svelte`.
 
 > If you don't know Svelte and are using an LLM to code for you, remember to ask it to write in Svelte 5 syntax.
 
+### Static Files
+All static files (e.g. `logo.svg`, `favicon.svg`, images, css files, etc.) should be put in the `afterpython/static/` directory.
+They will be automatically copied to the `afterpython/_website/static/` directory during `ap build`.
 
 ---
 ## Work in Progress 🚧

afterpython/doc/quickstart.md

@@ -30,6 +30,8 @@ A project website is basically a website that serves as the **homepage for your
 
 It aggregates and presents all your content in one place, including documentation, blog posts, tutorials, examples, and how-to guides.
 
+To **set the logo and favicon** for the project website, put your `logo.svg` and `favicon.svg` in the `afterpython/static/` directory.
+
 See [](project_website.md)  for more details.
 
 ---

afterpython/doc/references/cli_commands.md

@@ -1 +1,8 @@
 # CLI Commands
+
+:::{caution}
+Since configuration files are stored in `afterpython/` rather than the root directory (where `pyproject.toml` lives), some tools that only search the root directory by default (e.g., [pre-commit]) require special handling. You have two options:
+
+1. Use CLI commands wrapped by `ap` (e.g., `ap pre-commit ...`), which will automatically use the configuration files in `afterpython/` by default,
+2. Move the configuration files to the root directory manually if you prefer using native commands directly (e.g., `pre-commit ...`)
+:::