Getting Started

Relevant source files

• .gitignore
• LICENSE
• README.md
• afterpython/doc/myst.yml
• afterpython/doc/overview.md
• afterpython/doc/quickstart.md

This page guides you through setting up afterpython in your Python project, from installing prerequisites through running the initialization command and understanding the generated project structure. For detailed information about individual configuration files, see Configuration Files. For CLI command reference, see CLI Commands.

---

Purpose and Scope

This guide covers:

• Installing afterpython and its prerequisites.
• Running ap init to bootstrap your project.
• Understanding the directory structure and files created during initialization.
• Verifying your setup is ready for development.

This page focuses on initial setup. For development workflows, see Development Workflow. For customization options, see Advanced Topics.

---

Prerequisites

Before installing afterpython, ensure you have the following tools installed:

Tool	Minimum Version	Purpose	Installation
Python	3.11+	Core runtime	python.org
Node.js	18+	Website build system	nodejs.org
pnpm	8+	Node.js package manager	npm install -g pnpm
uv	Latest	Python package manager (recommended)	docs.astral.sh/uv/
Git	Any recent	Version control	git-scm.com

Optional but recommended:

• pixi - For multi-version testing and reproducible environments (see Dependency Management).

Sources: README.md6-11 README.md27-28 afterpython/doc/overview.md45-57

---

Installation Methods

Method 1: Using uv (Recommended)

uv is the preferred tool for managing afterpython as a development dependency.

Method 2: Using pip

Troubleshooting Installation

mystmd (a core dependency) sometimes has restrictive version constraints for platformdirs and nodeenv. If you encounter resolution errors, add overrides to your pyproject.toml:

Sources: README.md64-71 afterpython/doc/quickstart.md11-25

---

Project Initialization Workflow

The following diagram shows the complete initialization sequence when you run ap init:

Sources: afterpython/doc/quickstart.md14-38 afterpython/doc/overview.md27-30

---

Running ap init

Basic Usage

Initialization Steps

1. Directory Creation: Creates afterpython/ and afterpython/static/.
2. pyproject.toml: Configures uv as the build backend and sets up project URLs.
3. afterpython.toml: Creates the primary configuration file for website metadata.
4. MyST Configuration: Initializes myst.yml in five content directories: doc/, blog/, tutorial/, example/, and guide/.
5. Website Template: Clones the project-website-template into afterpython/_website/.
6. GitHub Workflows: Generates ci.yml, deploy.yml, and release.yml.
7. Branch Protection: Provides the option to run ap init-branch-rules.

Sources: afterpython/doc/quickstart.md27-38 afterpython/doc/quickstart.md87-92

---

Generated Project Structure

After running ap init, your project will have the following structure:

Directory Reference

Path	Purpose
afterpython/	Main configuration and content directory.
afterpython/static/	Static assets (images, logos, thumbnails).
afterpython/doc/	Documentation content (MyST/Jupyter).
afterpython/blog/	Blog posts (MyST/Jupyter).
afterpython/_website/	SvelteKit website template source.
afterpython/_build/	Temporary build artifacts.
.github/workflows/	GitHub Actions CI/CD workflows.

Sources: afterpython/doc/quickstart.md29-34 afterpython/doc/quickstart.md47-49 .gitignore199-214

---

Verifying Your Setup

1. Check Directory Structure

2. Test Development Server

3. Verify CLI Access

Sources: afterpython/doc/quickstart.md58-68 afterpython/doc/overview.md34-41

---

Next Steps

For details on specific initialization steps and structure, see the following child pages:

• Installation and Prerequisites — Detailed system requirements and tool versions.
• Project Initialization (ap init) — Deep dive into the initialization flags and logic.
• Project Structure and Paths — Explanation of how content folders and the _website directory interact.

Sources: afterpython/doc/quickstart.md49 afterpython/doc/quickstart.md74-76