This page provides a comprehensive reference for all environment variables that control AfterPython's runtime behavior. These variables can be set in your shell, in a .env file, or in CI/CD workflows to customize how AfterPython processes content, builds websites, and synchronizes configuration.
For configuration files that persist settings (like pyproject.toml and afterpython.toml), see Configuration Files. For command-line options, see CLI Commands. For CI/CD workflow configuration, see CI/CD and Deployment.
The table below lists all environment variables recognized by AfterPython:
| Variable | Default | Type | Purpose | Related Commands |
|---|---|---|---|---|
AP_AUTO_SYNC | 0 | Boolean (0 or 1) | Automatically synchronize configuration files before builds | ap build, ap dev |
AP_MOLAB_BADGE | 1 | Boolean (0 or 1) | Add Molab badges to Jupyter notebooks during build | ap build |
BASE_PATH | "" (empty) | String | Base path for GitHub Pages subdirectory deployment | ap build, ap preview |
Sources: .env.example1-3 afterpython/doc/references/environment_variables.md1-9
Create a .env file in your project root:
Template: AfterPython provides .env.example as a template. Copy it to .env and modify as needed.
Set variables in GitHub Actions workflows:
Export variables before running commands:
Sources: .env.example1-3
AP_AUTO_SYNCDefault: 0 (disabled)
Type: Boolean (0 = disabled, 1 = enabled)
Description: When enabled, automatically runs configuration synchronization before build operations. This ensures that changes to pyproject.toml or afterpython.toml are propagated to authors.yml and all myst.yml files without manually running ap sync.
Behavior:
AP_AUTO_SYNC=0: No automatic synchronization. Run ap sync manually when configuration changes.AP_AUTO_SYNC=1: Automatically executes synchronization logic before ap build and ap dev operations.Use Cases:
1 to avoid forgetting to run ap sync after updating authors or project metadata1 to ensure builds always use latest configuration0 if you prefer explicit control over synchronizationRelated Systems:
ap sync command (see ap sync - Synchronize Configuration)Affected Files:
pyproject.toml, afterpython.tomlauthors.yml, doc/myst.yml, blog/myst.yml, tutorial/myst.yml, example/myst.yml, guide/myst.ymlSources: .env.example1 afterpython/doc/references/environment_variables.md3-4 afterpython/doc/myst.md99-105
Sources: afterpython/doc/myst.md99-105 afterpython/doc/references/environment_variables.md3-4
AP_MOLAB_BADGEDefault: 1 (enabled)
Type: Boolean (0 = disabled, 1 = enabled)
Description: Controls whether Molab badges are automatically added to Jupyter notebook outputs during the build process. Molab is a cloud service by Marimo that allows users to run Jupyter notebooks in the cloud for free.
Behavior:
AP_MOLAB_BADGE=0: No badges added. Notebooks rendered as-is.AP_MOLAB_BADGE=1: Molab badges automatically inserted into notebook HTML output, enabling one-click cloud execution.Badge Appearance:
When enabled, a badge appears in the rendered notebook allowing visitors to open and run the notebook in Molab's cloud environment without any local setup.
Use Cases:
Related Content Types:
doc/)tutorial/)example/)guide/)blog/)Any content directory containing .ipynb files is affected by this setting.
Related Systems:
Sources: .env.example2 afterpython/doc/references/environment_variables.md7-8 afterpython/doc/myst.md37-43
BASE_PATHDefault: "" (empty string)
Type: String (URL path segment)
Description: Configures the base URL path for the website when deploying to GitHub Pages subdirectories. GitHub Pages serves repositories at https://username.github.io/repo-name/, requiring all asset URLs to include the /repo-name prefix.
Behavior:
BASE_PATH="": Website assumes root-level deployment (e.g., custom domain or username.github.io)BASE_PATH="/repo-name": Website prepends /repo-name to all internal URLs and asset referencesExamples:
Technical Implementation:
The BASE_PATH is injected into the SvelteKit build process, affecting:
/static/... becomes /repo-name/static/...)/blog becomes /repo-name/blog)Use Cases:
https://username.github.io/repo-name/ap dev or ap previewCI/CD Configuration:
GitHub Actions deploy workflow should set BASE_PATH based on repository name:
Common Issues:
| Issue | Symptom | Solution |
|---|---|---|
| Missing BASE_PATH | 404 errors for assets on GitHub Pages | Set BASE_PATH=/repo-name |
| Incorrect BASE_PATH | Pages load but links broken | Verify BASE_PATH matches URL structure |
| BASE_PATH in development | Local dev server shows 404s | Remove BASE_PATH for ap dev |
Related Systems:
Sources: Table of contents reference to section 6.5
Sources: .env.example1-3 afterpython/doc/references/environment_variables.md1-9
Recommended settings for local development:
Recommended settings for GitHub Actions:
Recommended settings when deploying to custom domain:
Sources: .env.example1-3
Environment variables are resolved in the following order (highest to lowest priority):
AP_AUTO_SYNC=1 ap buildexport AP_AUTO_SYNC=1; ap build.env file: Variables loaded from .env in project rootNote: The .env file is not automatically loaded by AfterPython. It serves as documentation and requires manual sourcing or tool support (e.g., direnv, dotenv).
Sources: .env.example1-3
The following table shows how environment variables interact with each other and CLI commands:
| Command | Reads AP_AUTO_SYNC | Reads AP_MOLAB_BADGE | Reads BASE_PATH |
|---|---|---|---|
ap init | No | No | No |
ap sync | No | No | No |
ap build | Yes | Yes | Yes |
ap dev | Yes | Yes | No* |
ap preview | No | No | Yes |
* ap dev serves content without BASE_PATH rewriting since it's for local development.
Sources: .env.example1-3 afterpython/doc/references/environment_variables.md1-9
AP_AUTO_SYNC=1 in CI/CD to ensure fresh builds.env.example as a template for your .env fileBASE_PATH in deploy workflow, not in .env.env files with sensitive values to version controlBASE_PATH for local development with ap dev.env files are automatically loaded (they require tool support)Sources: .env.example1-3
pyproject.toml and afterpython.tomlSources: .env.example1-3 afterpython/doc/references/environment_variables.md1-9 afterpython/doc/myst.md37-105
Refresh this wiki