markbook 0.1.0__tar.gz

markbook-0.1.0/.gitignore

@@ -0,0 +1,90 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+venv/
+env/
+.venv/
+.env/
+
+# Distribution / packaging
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook checkpoints
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre
+.pyre/
+
+# Pytype
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# VS Code
+.vscode/
+
+# JetBrains IDEs (PyCharm, etc.)
+.idea/
+
+# MacOS
+.DS_Store
+
+# Windows
+Thumbs.db
+ehthumbs.db
+desktop.ini
+
+# dotenv files
+.env
+
+.ruff_cache/
+
+site/
+
+.claude/

markbook-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+        exclude: ^mkdocs\.yml$
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ["--maxkb=1000"]
+      - id: check-case-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.13.1
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.15.2
+    hooks:
+      - id: pyupgrade
+        args: [--py39-plus]

markbook-0.1.0/LICENCSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathis Kristoffer Arends
+
+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.

markbook-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: markbook
+Version: 0.1.0
+Summary: Write Jupyter notebooks in Markdown, render them beautifully
+Requires-Python: >=3.14
+Requires-Dist: nbformat>=5.10.4
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=14.3.3
+Requires-Dist: typer>=0.24.1
+Requires-Dist: watchdog>=6.0.0
+Description-Content-Type: text/markdown
+
+# markbook
+
+A CLI tool that compiles a custom Markdown DSL into styled Jupyter Notebooks (`.ipynb`).
+Write in plain Markdown, render beautifully in Jupyter.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+### Build a notebook
+
+```bash
+markbook build notebook.md
+markbook build notebook.md -o output.ipynb
+```
+
+### Watch for changes
+
+```bash
+markbook watch notebook.md
+```
+
+Recompiles automatically on every save.
+
+## DSL Syntax
+
+### Frontmatter
+
+YAML block at the top of the file. Renders as a title heading and author name in the first cell.
+
+```yaml
+---
+title: "My Notebook"
+kernel: python3
+author: "Your Name"
+---
+```
+
+### Headings
+
+Use `##`, `###` and `####` to structure your notebook into chapters and sections. Each heading becomes its own styled markdown cell. Optional anchor IDs enable linking from the table of contents.
+
+```markdown
+## 1. Business Understanding {#chapter1}
+
+### 1.1 Project Context {#chap1_1}
+
+#### 1.1.1 Goals {#chap1_1_1}
+```
+
+| Level  | Rendered Style                                     |
+|--------|----------------------------------------------------|
+| `##`   | Large (1.6em), accent color `#2E86AB`, 4px left border |
+| `###`  | Medium (1.3em), accent color `#2E86AB`, 3px left border |
+| `####` | Small (1.1em), muted color `#555`, no border       |
+
+Anchor IDs (`{#id}`) are optional — if omitted, markbook auto-generates them by slugifying the heading text.
+
+> **Note:** `#` (h1) is **not** recognized as a chapter heading. It passes through as regular markdown. Use `##` and below.
+
+### Table of Contents
+
+Place `[TOC]` on its own line to auto-generate a linked table of contents from all headings in the document:
+
+```markdown
+[TOC]
+```
+
+This produces a cell like:
+
+```
+## Gliederung
+
+* **[1. Business Understanding](#chapter1)**
+    * [1.1 Project Context](#chap1_1)
+        * [1.1.1 Goals](#chap1_1_1)
+* **[2. Data Loading](#chapter2)**
+    * [2.1 Imports](#chap2_1)
+```
+
+`##` headings become bold top-level entries, `###` are indented, `####` double-indented. All entries link to their heading's anchor ID.
+
+### Code Cells
+
+Fenced code blocks with a recognized language tag become notebook code cells:
+
+````markdown
+```python
+import pandas as pd
+df = pd.read_csv("data.csv")
+```
+````
+
+Supported languages: `python`, `bash`, `sql`, `r`, `julia`, `sh`, `javascript`, `typescript`, `java`, `c`, `cpp`, `go`, `rust`.
+
+Fenced blocks with other or no language tags become markdown cells.
+
+### Section Dividers
+
+A horizontal rule becomes a styled `<hr>`:
+
+```markdown
+---
+```
+
+### Regular Markdown
+
+Everything else (paragraphs, bold, italic, lists, tables, blockquotes) passes through as-is into markdown cells.
+
+## Example
+
+See [`examples/diabetes.md`](examples/diabetes.md) for a full example. Build it with:
+
+```bash
+markbook build examples/diabetes.md
+```
+
+## Dependencies
+
+- [nbformat](https://github.com/jupyter/nbformat) - Jupyter notebook format
+- [PyYAML](https://pyyaml.org/) - YAML frontmatter parsing
+- [Typer](https://typer.tiangolo.com/) - CLI framework
+- [Rich](https://rich.readthedocs.io/) - Terminal output
+- [watchdog](https://github.com/gorakhargosh/watchdog) - File watching

markbook-0.1.0/README.md

@@ -0,0 +1,128 @@
+# markbook
+
+A CLI tool that compiles a custom Markdown DSL into styled Jupyter Notebooks (`.ipynb`).
+Write in plain Markdown, render beautifully in Jupyter.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+### Build a notebook
+
+```bash
+markbook build notebook.md
+markbook build notebook.md -o output.ipynb
+```
+
+### Watch for changes
+
+```bash
+markbook watch notebook.md
+```
+
+Recompiles automatically on every save.
+
+## DSL Syntax
+
+### Frontmatter
+
+YAML block at the top of the file. Renders as a title heading and author name in the first cell.
+
+```yaml
+---
+title: "My Notebook"
+kernel: python3
+author: "Your Name"
+---
+```
+
+### Headings
+
+Use `##`, `###` and `####` to structure your notebook into chapters and sections. Each heading becomes its own styled markdown cell. Optional anchor IDs enable linking from the table of contents.
+
+```markdown
+## 1. Business Understanding {#chapter1}
+
+### 1.1 Project Context {#chap1_1}
+
+#### 1.1.1 Goals {#chap1_1_1}
+```
+
+| Level  | Rendered Style                                     |
+|--------|----------------------------------------------------|
+| `##`   | Large (1.6em), accent color `#2E86AB`, 4px left border |
+| `###`  | Medium (1.3em), accent color `#2E86AB`, 3px left border |
+| `####` | Small (1.1em), muted color `#555`, no border       |
+
+Anchor IDs (`{#id}`) are optional — if omitted, markbook auto-generates them by slugifying the heading text.
+
+> **Note:** `#` (h1) is **not** recognized as a chapter heading. It passes through as regular markdown. Use `##` and below.
+
+### Table of Contents
+
+Place `[TOC]` on its own line to auto-generate a linked table of contents from all headings in the document:
+
+```markdown
+[TOC]
+```
+
+This produces a cell like:
+
+```
+## Gliederung
+
+* **[1. Business Understanding](#chapter1)**
+    * [1.1 Project Context](#chap1_1)
+        * [1.1.1 Goals](#chap1_1_1)
+* **[2. Data Loading](#chapter2)**
+    * [2.1 Imports](#chap2_1)
+```
+
+`##` headings become bold top-level entries, `###` are indented, `####` double-indented. All entries link to their heading's anchor ID.
+
+### Code Cells
+
+Fenced code blocks with a recognized language tag become notebook code cells:
+
+````markdown
+```python
+import pandas as pd
+df = pd.read_csv("data.csv")
+```
+````
+
+Supported languages: `python`, `bash`, `sql`, `r`, `julia`, `sh`, `javascript`, `typescript`, `java`, `c`, `cpp`, `go`, `rust`.
+
+Fenced blocks with other or no language tags become markdown cells.
+
+### Section Dividers
+
+A horizontal rule becomes a styled `<hr>`:
+
+```markdown
+---
+```
+
+### Regular Markdown
+
+Everything else (paragraphs, bold, italic, lists, tables, blockquotes) passes through as-is into markdown cells.
+
+## Example
+
+See [`examples/diabetes.md`](examples/diabetes.md) for a full example. Build it with:
+
+```bash
+markbook build examples/diabetes.md
+```
+
+## Dependencies
+
+- [nbformat](https://github.com/jupyter/nbformat) - Jupyter notebook format
+- [PyYAML](https://pyyaml.org/) - YAML frontmatter parsing
+- [Typer](https://typer.tiangolo.com/) - CLI framework
+- [Rich](https://rich.readthedocs.io/) - Terminal output
+- [watchdog](https://github.com/gorakhargosh/watchdog) - File watching

markbook-0.1.0/docs/skills/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: markbook
+description: Generate well-structured Jupyter Notebooks by writing Markdown DSL files and compiling them with the markbook CLI
+version: 0.1.0
+---
+
+# markbook — Generate Jupyter Notebooks from Markdown
+
+You are using **markbook**, a CLI that compiles a Markdown DSL into styled Jupyter Notebooks (`.ipynb`). Your workflow is: write a `.md` file using markbook's DSL syntax, then compile it.
+
+## Workflow
+
+### 1. Write the `.md` file
+
+Create a Markdown file using markbook's DSL. See [SYNTAX.md](SYNTAX.md) for the complete reference.
+
+### 2. Compile to notebook
+
+```bash
+markbook build <file>.md                # outputs <file>.ipynb
+markbook build <file>.md -o output.ipynb  # custom output path
+```
+
+That's it. There are only two commands: `build` and `watch` (auto-rebuild on save).
+
+## How to Structure a Good Notebook
+
+When generating a `.md` file for markbook, follow this structure:
+
+### Start with frontmatter
+
+Always begin the file with YAML frontmatter:
+
+```yaml
+---
+title: "Descriptive Title"
+kernel: python3
+author: "Author Name"
+---
+```
+
+### Add a table of contents
+
+Place `[TOC]` right after frontmatter for navigable notebooks. It auto-generates from all headings.
+
+### Use `---` dividers between major sections
+
+Dividers create visual separation. Place them between top-level chapters.
+
+### Structure with `##`, `###`, `####` headings
+
+Use heading levels consistently:
+
+- `##` — top-level chapters (e.g., `## 1. Data Loading`)
+- `###` — sub-sections (e.g., `### 1.1 Import Libraries`)
+- `####` — minor sections when needed
+
+Always add anchor IDs to headings for TOC links: `## Title {#anchor_id}`
+
+### Alternate prose and code
+
+Good notebooks explain what the code does **before** the code cell. Write a markdown paragraph or bullet list, then the code block:
+
+```markdown
+### 2.1 Load the Dataset {#load_data}
+
+We load the CSV and inspect the first rows.
+
+\`\`\`python
+import pandas as pd
+df = pd.read_csv("data.csv")
+df.head()
+\`\`\`
+```
+
+### Use recognized languages for code cells
+
+Only these language tags produce code cells:
+`python`, `bash`, `sql`, `r`, `julia`, `sh`, `javascript`, `typescript`, `java`, `c`, `cpp`, `go`, `rust`
+
+Any other tag (or no tag) creates a markdown cell — useful for showing example output or pseudocode.
+
+## Full Template
+
+Here is a template for a data science notebook:
+
+```markdown
+---
+title: "Project Title"
+kernel: python3
+author: "Your Name"
+---
+
+[TOC]
+
+---
+
+## 1. Introduction {#intro}
+
+Brief description of the project goal.
+
+- Objective 1
+- Objective 2
+
+---
+
+## 2. Data Loading {#data}
+
+### 2.1 Imports {#imports}
+
+\`\`\`python
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+\`\`\`
+
+### 2.2 Read Data {#read_data}
+
+\`\`\`python
+df = pd.read_csv("data.csv")
+print(f"Shape: {df.shape}")
+df.head()
+\`\`\`
+
+---
+
+## 3. Exploratory Analysis {#eda}
+
+### 3.1 Overview {#overview}
+
+\`\`\`python
+df.describe()
+\`\`\`
+
+### 3.2 Visualizations {#viz}
+
+\`\`\`python
+fig, ax = plt.subplots(figsize=(8, 5))
+
+# plotting code
+
+plt.show()
+\`\`\`
+
+---
+
+## 4. Modeling {#modeling}
+
+### 4.1 Train/Test Split {#split}
+
+\`\`\`python
+from sklearn.model_selection import train_test_split
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)
+\`\`\`
+
+---
+
+## 5. Evaluation {#eval}
+
+\`\`\`python
+from sklearn.metrics import classification_report
+print(classification_report(y_test, y_pred))
+\`\`\`
+```
+
+## Common Mistakes to Avoid
+
+- **Missing frontmatter** — always start with `---` on line 1. Without it, no title/kernel metadata.
+- **Using `#` (h1)** — single `#` is NOT recognized as a chapter. Use `##` and below.
+- **Forgetting anchor IDs** — without `{#id}`, TOC links still work (auto-slugified), but explicit anchors are cleaner.
+- **Unclosed code fences** — every ` ``` ` must have a matching closing ` ``` `. Unclosed blocks cause a build error.
+- **Wrong language tag** — `\`\`\`py`does not work, use`\`\`\`python`. Tags are matched exactly against the supported list.
+- **`---` on line 0** — the first `---` in the file always opens frontmatter, not a divider. Dividers only work after frontmatter.