akceo 0.1.0__tar.gz

akceo-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.claude/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Virtual envs
+.venv/
+.env
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.pyright/
+
+# Built example decks
+examples/**/*.html

akceo-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-24
+
+The first release.
+
+### Added
+
+- Published on PyPI: `uv tool install akceo` or `pipx install akceo`.
+- `akceo build` renders a Markdown deck into one self-contained HTML file.
+- `akceo themes` lists the built-in themes.
+- Six layouts: `title`, `bullets`, `split`, `steps`, `table` and `image`.
+- Built-in `midnight` and `paper` themes. Custom themes are CSS files that set akceo's tokens.
+- PNG, JPEG and WebP images are shrunk and embedded; SVG is embedded as-is.
+- Mermaid diagrams: `image: flow.mmd` is drawn as SVG when the page opens. akceo includes
+  Mermaid, so there's nothing else to install. The build checks each diagram with Mermaid's own
+  parser and stops on a syntax error, naming the line in the `.mmd` file. It also stops on a
+  diagram that would load or link to anything outside the deck, and on one longer than Mermaid's
+  50,000-character limit. A deck with a diagram grows by about 5.6 MB.
+- The built page carries a Content-Security-Policy, so the browser refuses to load anything from
+  outside the file. A web font or `@import` in a custom theme doesn't load; use installed fonts,
+  or embed one as a `data:` URI.
+- `akceo check deck.md` runs every check a build runs, diagrams included, without writing a file.
+- Per-slide style overrides: `style-h1`, `style-h2`, `style-lead`, `style-ul`, `style-ol` and
+  `style-sub` add inline CSS to that element, for one-off spacing fixes. They can't reference
+  files or URLs.
+- `image-frame: no`, for the whole deck or one slide, drops the white panel behind images.
+  Mermaid diagrams without a frame are drawn in the deck theme's colors.
+- Deck errors name the file, line and slide; theme and image errors name the file. Content a
+  layout doesn't use is reported with the list of what that layout takes.
+- The URL hash tracks the current slide: `deck.html#4` opens slide 4, and a reload stays put.
+- Author notes: a line starting with `//` is dropped from the page, so reminders can sit next to
+  the slide they're about.
+- A `split` slide with no `image:` line builds with a dashed placeholder box, so a slide can be
+  set up before its image exists.
+- `akceo viewer` writes `md-viewer.html`, a speaker-notes viewer for a second browser tab. In
+  Chrome and Edge it refreshes live when the notes file changes.
+- Example speaker notes for the demo deck.
+- Docs: the speaker-notes setup, and how Akceo works (plain terms, user experience, internals),
+  with Mermaid diagrams.

akceo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Colinsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

akceo-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.5
+Name: akceo
+Version: 0.1.0
+Summary: Build self-contained HTML slide decks from Markdown.
+Project-URL: Repository, https://github.com/LunarCommand/akceo
+Project-URL: Documentation, https://github.com/LunarCommand/akceo/blob/main/docs/syntax.md
+Project-URL: Changelog, https://github.com/LunarCommand/akceo/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/LunarCommand/akceo/issues
+Author-email: Chris Colinsky <chris@lunarcommand.xyz>
+License-Expression: MIT AND Apache-2.0 AND BSD-3-Clause AND ISC AND EPL-2.0 AND (MPL-2.0 OR Apache-2.0) AND Unlicense
+License-File: LICENSE
+License-File: src/akceo/assets/vendor/mermaid/LICENSE
+License-File: src/akceo/assets/vendor/mermaid/THIRD_PARTY_NOTICES
+Keywords: cli,html,markdown,mermaid,presentation,slides
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics :: Presentation
+Requires-Python: >=3.12
+Requires-Dist: mini-racer>=0.14.1
+Requires-Dist: pillow>=10.0
+Description-Content-Type: text/markdown
+
+# Akceo
+
+Build self-contained HTML slide decks from Markdown.
+
+You write slides in one Markdown file and run one command. You get a single HTML file with every
+image embedded in it. Large PNG, JPEG and WebP images are shrunk first. Mermaid `.mmd` diagrams
+are checked at build time and drawn when the page opens, with a copy of Mermaid that akceo
+includes, so there's nothing else to install. The file has no external assets, so it opens
+straight from disk, works offline, and survives being emailed or copied anywhere.
+
+## Install
+
+Needs Python 3.12 or newer. Install the `akceo` command from PyPI with
+[uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/):
+
+```sh
+uv tool install akceo
+pipx install akceo
+```
+
+To try changes that aren't released yet, install from the repository instead:
+
+```sh
+uv tool install git+https://github.com/LunarCommand/akceo
+```
+
+To work on akceo itself, install your checkout in editable mode so the `akceo` command always
+runs your latest source:
+
+```sh
+git clone https://github.com/LunarCommand/akceo.git
+uv tool install --editable ./akceo
+```
+
+## Quickstart
+
+Write `deck.md`:
+
+```markdown
+title: Q3 Review
+theme: midnight
+
+---
+
+layout: title
+kicker: Q3 review
+meta: Platform team · September 2026
+
+# Shipping faster
+
+---
+
+kicker: The problem
+
+## Builds take too long
+
+- **Full rebuilds** on every change.
+- CI queues back up at ==peak hours==.
+```
+
+Build it:
+
+```sh
+akceo build deck.md          # writes deck.html next to deck.md
+akceo build deck.md -o talk.html --theme paper
+akceo check deck.md          # runs every check, diagrams included, and writes nothing
+```
+
+Open `deck.html` in a browser to present:
+
+| Key | Action |
+| --- | --- |
+| `→`, `Space`, `PageDown`, click right half | Next slide |
+| `←`, `PageUp`, click left half | Previous slide |
+| `Home`, `End` | First, last slide |
+| `F` | Toggle full screen |
+
+A click while text is selected doesn't change slides, so you can copy text from a slide.
+
+The address bar shows the current slide as `#N`, so `deck.html#4` opens on slide 4 and a reload
+stays on the slide you were on.
+
+`examples/demo/deck.md` uses every layout and markup feature. Build it with
+`akceo build examples/demo/deck.md`.
+
+## Layouts
+
+| Layout | For | Content |
+| --- | --- | --- |
+| `title` | Opening and section slides | `#` heading, kicker, meta line |
+| `bullets` | Most slides (the default) | `##` heading, lead, list, paragraph |
+| `split` | A diagram with commentary | image, `##` heading, phases, lists, note |
+| `steps` | A sequence | `##` heading, paragraph, numbered list |
+| `table` | Comparisons | `##` heading, table |
+| `image` | A diagram on its own | image, kicker |
+
+The full format is in [docs/syntax.md](docs/syntax.md). It covers config keys, slide keys, blocks
+and inline markup.
+
+## Themes
+
+```sh
+akceo themes                          # list the built-in themes
+akceo build deck.md --theme paper     # a built-in theme
+akceo build deck.md --theme brand.css # your own theme
+```
+
+A deck can also set `theme:` in its config block. The `--theme` flag overrides it.
+
+`midnight` (dark, the default) and `paper` (light) are built in. A custom theme is a CSS file
+that sets akceo's color and font tokens. The simplest start is a copy of
+[`src/akceo/themes/midnight.css`](src/akceo/themes/midnight.css). The token list is in
+[docs/syntax.md](docs/syntax.md#themes).
+
+## Speaker notes
+
+Keep your notes in a Markdown file and read them in a second browser tab, while you share only
+the deck tab in your call.
+
+```sh
+akceo viewer    # writes md-viewer.html into the current folder
+```
+
+Open `md-viewer.html` next to your deck, for example with Chrome's split view, and open your
+notes file in it. In Chrome and Edge it refreshes by itself when you save the notes.
+`examples/demo/speaker-notes.md` goes with the demo deck. The setup is in
+[docs/speaker-notes.md](docs/speaker-notes.md).
+
+## How it works
+
+[docs/how-it-works.md](docs/how-it-works.md) explains Akceo at three levels: in plain terms,
+from the user's side, and under the hood. It has diagrams of the build pipeline, the data model
+and the notes viewer.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run pyright
+uv run pre-commit install   # optional: run these checks on every commit
+```
+
+Releases are published to PyPI by pushing a version tag; [docs/RELEASING.md](docs/RELEASING.md)
+has the steps.
+
+## Branding
+
+Akceo comes from the Latin *actio*, "the act of doing". The spelling ends in *ceo* to tie it to
+the executives who give so many decks: executive action. The full naming rationale is in
+[docs/branding.md](docs/branding.md). The domain is akceo.ai.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

akceo-0.1.0/README.md

@@ -0,0 +1,156 @@
+# Akceo
+
+Build self-contained HTML slide decks from Markdown.
+
+You write slides in one Markdown file and run one command. You get a single HTML file with every
+image embedded in it. Large PNG, JPEG and WebP images are shrunk first. Mermaid `.mmd` diagrams
+are checked at build time and drawn when the page opens, with a copy of Mermaid that akceo
+includes, so there's nothing else to install. The file has no external assets, so it opens
+straight from disk, works offline, and survives being emailed or copied anywhere.
+
+## Install
+
+Needs Python 3.12 or newer. Install the `akceo` command from PyPI with
+[uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/):
+
+```sh
+uv tool install akceo
+pipx install akceo
+```
+
+To try changes that aren't released yet, install from the repository instead:
+
+```sh
+uv tool install git+https://github.com/LunarCommand/akceo
+```
+
+To work on akceo itself, install your checkout in editable mode so the `akceo` command always
+runs your latest source:
+
+```sh
+git clone https://github.com/LunarCommand/akceo.git
+uv tool install --editable ./akceo
+```
+
+## Quickstart
+
+Write `deck.md`:
+
+```markdown
+title: Q3 Review
+theme: midnight
+
+---
+
+layout: title
+kicker: Q3 review
+meta: Platform team · September 2026
+
+# Shipping faster
+
+---
+
+kicker: The problem
+
+## Builds take too long
+
+- **Full rebuilds** on every change.
+- CI queues back up at ==peak hours==.
+```
+
+Build it:
+
+```sh
+akceo build deck.md          # writes deck.html next to deck.md
+akceo build deck.md -o talk.html --theme paper
+akceo check deck.md          # runs every check, diagrams included, and writes nothing
+```
+
+Open `deck.html` in a browser to present:
+
+| Key | Action |
+| --- | --- |
+| `→`, `Space`, `PageDown`, click right half | Next slide |
+| `←`, `PageUp`, click left half | Previous slide |
+| `Home`, `End` | First, last slide |
+| `F` | Toggle full screen |
+
+A click while text is selected doesn't change slides, so you can copy text from a slide.
+
+The address bar shows the current slide as `#N`, so `deck.html#4` opens on slide 4 and a reload
+stays on the slide you were on.
+
+`examples/demo/deck.md` uses every layout and markup feature. Build it with
+`akceo build examples/demo/deck.md`.
+
+## Layouts
+
+| Layout | For | Content |
+| --- | --- | --- |
+| `title` | Opening and section slides | `#` heading, kicker, meta line |
+| `bullets` | Most slides (the default) | `##` heading, lead, list, paragraph |
+| `split` | A diagram with commentary | image, `##` heading, phases, lists, note |
+| `steps` | A sequence | `##` heading, paragraph, numbered list |
+| `table` | Comparisons | `##` heading, table |
+| `image` | A diagram on its own | image, kicker |
+
+The full format is in [docs/syntax.md](docs/syntax.md). It covers config keys, slide keys, blocks
+and inline markup.
+
+## Themes
+
+```sh
+akceo themes                          # list the built-in themes
+akceo build deck.md --theme paper     # a built-in theme
+akceo build deck.md --theme brand.css # your own theme
+```
+
+A deck can also set `theme:` in its config block. The `--theme` flag overrides it.
+
+`midnight` (dark, the default) and `paper` (light) are built in. A custom theme is a CSS file
+that sets akceo's color and font tokens. The simplest start is a copy of
+[`src/akceo/themes/midnight.css`](src/akceo/themes/midnight.css). The token list is in
+[docs/syntax.md](docs/syntax.md#themes).
+
+## Speaker notes
+
+Keep your notes in a Markdown file and read them in a second browser tab, while you share only
+the deck tab in your call.
+
+```sh
+akceo viewer    # writes md-viewer.html into the current folder
+```
+
+Open `md-viewer.html` next to your deck, for example with Chrome's split view, and open your
+notes file in it. In Chrome and Edge it refreshes by itself when you save the notes.
+`examples/demo/speaker-notes.md` goes with the demo deck. The setup is in
+[docs/speaker-notes.md](docs/speaker-notes.md).
+
+## How it works
+
+[docs/how-it-works.md](docs/how-it-works.md) explains Akceo at three levels: in plain terms,
+from the user's side, and under the hood. It has diagrams of the build pipeline, the data model
+and the notes viewer.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run pyright
+uv run pre-commit install   # optional: run these checks on every commit
+```
+
+Releases are published to PyPI by pushing a version tag; [docs/RELEASING.md](docs/RELEASING.md)
+has the steps.
+
+## Branding
+
+Akceo comes from the Latin *actio*, "the act of doing". The spelling ends in *ceo* to tie it to
+the executives who give so many decks: executive action. The full naming rationale is in
+[docs/branding.md](docs/branding.md). The domain is akceo.ai.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

akceo-0.1.0/docs/RELEASING.md

@@ -0,0 +1,97 @@
+# Releasing Akceo
+
+Pushing a version tag, such as `v0.1.0`, runs `.github/workflows/release.yml`. It tests the
+package, builds it, publishes it to PyPI as `akceo`, and creates a GitHub Release whose notes are
+that version's section of `CHANGELOG.md`.
+
+## One-time setup
+
+1. **PyPI trusted publisher.** On PyPI, add a trusted publisher for the project `akceo`. Before the
+   first release the project doesn't exist yet, so add it as a *pending* publisher under your
+   account's publishing settings. Use these values:
+
+   | Field | Value |
+   | --- | --- |
+   | Owner | `LunarCommand` |
+   | Repository | `akceo` |
+   | Workflow | `release.yml` |
+   | Environment | `pypi` |
+
+   PyPI then trusts that workflow, so no API token is stored in GitHub.
+
+2. **GitHub environment.** In the repository settings, create an environment named `pypi`. Adding
+   yourself as a required reviewer is optional; it makes every publish wait for your approval.
+
+## Release steps
+
+1. **Bring the changelog up to date.** Every change since the last release that a user would
+   notice belongs in the `Unreleased` section of `CHANGELOG.md`. Compare with
+   `git log --oneline <last tag>..main`.
+
+2. **Check the docs.** For each change in the release, search the docs for the old wording, file
+   names and option descriptions, and update them: `README.md`, `docs/syntax.md`,
+   `docs/how-it-works.md`, `docs/speaker-notes.md` and the `--help` text in `src/akceo/cli.py`.
+
+3. **Set the version and date**, on a branch, in one commit:
+   - `pyproject.toml`: `version = "0.2.0"`. This is the only place the version is set; `akceo
+     --version` reads it from the installed package.
+   - `CHANGELOG.md`: rename `## [Unreleased]` to `## [0.2.0] - YYYY-MM-DD` with the date you'll tag
+     on, and add a new empty `## [Unreleased]` above it.
+   - Run `uv lock`, so `uv.lock` records the new version.
+
+4. **Review what's about to ship.** Before merging, look at the full change since the last
+   release (`git diff <last tag>..HEAD`) next to the new changelog section. Then merge to `main`.
+
+5. **Tag and push**, from the merged `main`:
+
+   ```sh
+   git checkout main && git pull
+   git tag v0.2.0
+   git push origin v0.2.0
+   ```
+
+   The tag must match the version in `pyproject.toml`. If the changelog date isn't today, fix it
+   before tagging.
+
+6. **The workflow does the rest:**
+   - checks that the tag matches `pyproject.toml` and that `CHANGELOG.md` has a section for it,
+     dated within a day of the tag
+   - runs ruff, pyright and pytest
+   - builds the sdist and the wheel
+   - publishes both to PyPI, waiting for approval if the `pypi` environment requires it
+   - creates the GitHub Release with the changelog section as its notes and the files attached
+
+## Checking a release
+
+- PyPI: <https://pypi.org/project/akceo/>
+- GitHub: the repository's Releases page
+- A clean install: `uv tool install akceo==0.2.0`, then `akceo --version` and a build of
+  `examples/demo/deck.md`
+
+## Versions
+
+Akceo follows semantic versioning. While the version is below 1.0, a minor release (0.x.0) may
+change the deck format or the command line; a patch release (0.1.x) only fixes bugs.
+
+## Troubleshooting
+
+**The workflow didn't start.** The tag has to match `v[0-9]*.[0-9]*.[0-9]*` and be pushed to
+GitHub. A tag created only locally does nothing.
+
+**"tag … doesn't match version …".** The tag and `pyproject.toml` disagree. Delete the tag
+(`git tag -d v0.2.0 && git push origin :refs/tags/v0.2.0`), fix the version on `main`, and tag
+again.
+
+**"CHANGELOG.md has no '## [0.2.0] - YYYY-MM-DD' heading".** Step 3 was missed, or the heading
+isn't exactly that form. Same fix as above.
+
+**"the 0.2.0 heading is dated …; date it the day you tag".** The changelog date has to be the
+release day, give or take one day for time zones. Fix the date on `main`, delete the tag and tag
+again.
+
+**The publish step fails.** Check that the PyPI trusted publisher's owner, repository, workflow file
+and environment exactly match the values in the setup table, and that the `pypi` environment exists.
+
+**A version was published with a mistake.** PyPI never lets a version number be used twice, even
+after deleting it. Fix the mistake and release the next patch version. If needed, yank the bad one
+on PyPI, which hides it from new installs without breaking pinned ones.

akceo-0.1.0/docs/branding.md

@@ -0,0 +1,22 @@
+# Branding
+
+- **Name:** Akceo. The command is `akceo`.
+- **Domain:** akceo.ai
+
+## Naming rationale
+
+The name moves through three steps.
+
+- **Actio** is "the act of doing, a driving force, or delivery". It is grounded in movement and
+  physical execution.
+- **Akcio** is a sharp, geometric spelling of Actio that looks like a cutting-edge AI or automated
+  tool.
+- **Akceo**: changing that one vowel does something incredibly powerful for a software brand: it
+  instantly connects your rapid deck builder to the Chief Executive Officer (CEO). Since
+  presentation decks are the ultimate tool for corporate leaders, startup founders, and pitch
+  masters, Akceo subtly tells the user: "This tool makes your slides look like they were built by
+  a high-level executive."
+
+By shifting from Akcio to Akceo, you also change the physical meaning. Instead of just meaning
+"action" or "delivery," it now means "Executive Action" or "Commanding Delivery." It sounds
+prestigious, fast, and highly authoritative.