docskin 0.3.1

Style your documents - convert Markdown files and GitHub issues into styled PDF documents in your corporate skin.

📄 docskin

Coverage Report

File	Stmts	Miss	Branch	BrPart	Cover	Missing
docskin
__init__.py	0	0	0	0	100%
__main__.py	6	6	2	0	0%	3–18
docskin/cli
__init__.py	23	1	2	1	92%	57
docskin/cli/commands
__init__.py	4	0	0	0	100%
github_issue.py	14	0	0	0	100%
markdown_file.py	12	0	0	0	100%
markdown_folder.py	17	0	4	0	100%
setup.py	5	1	0	0	80%	15
docskin/core
__init__.py	0	0	0	0	100%
content.py	39	8	4	2	77%	55–61, 72–76
converter.py	52	1	4	1	96%	54
github_api.py	27	6	2	1	76%	34, 39, 45–48
mermaid.py	27	0	0	0	100%
setup.py	32	22	4	0	28%	32, 44–85, 96–99, 109–110
styles.py	19	0	0	0	100%
tokens.py	20	15	6	0	19%	44–64
TOTAL	297	60	28	5	76%

Style your documents - convert Markdown files and GitHub issues into styled PDF documents in your corporate skin – with full support for CSS themes, logos, and directory processing.

🔧 Installation

uv sync

or in development mode:

uv sync --editable .

🚀 Usage

📁 Convert Markdown Files in a Directory

Converts all .md files in a directory to PDF format.

docskin md-dir \
  --input ./docs \
  --output ./pdfs \
  --css-style assets/markdown-dark.css \
  --logo assets/bosch-logo.png

📄 Convert a Single Markdown File

Converts a single file to PDF format.

docskin md \
  --input README.md \
  --output README.pdf \
  --css-style assets/minimal.css

🐙 Convert GitHub Issue to PDF

Converts a GitHub issue (e.g. on Bosch DevCloud) to PDF.

docskin github \
  --repo aos-stakeholder-tools/recompute-driving-cluster \
  --issue 197 \
  --api-base https://github.boschdevcloud.com/api/v3 \
  --output issue-197.pdf \
  --css-style assets/markdown-dark.css

🎨 Styling

Use any CSS file to define the appearance of the resulting PDFs.

Example styles:

• assets/markdown-dark.css – GitHub Dark Theme
• assets/minimal.css – Simple light theme
• assets/bosch.css – Bosch Corporate Design (experimental)

🖼️ Logo (optional)

Add a logo at the top of the PDF with --logo path/to/logo.png.

📦 CLI Overview

The docskin CLI provides the following commands:

• setup Installs all required Python and system dependencies for docskin, including WeasyPrint and its Linux libraries. Example:

  docskin setup
  

• md Converts a single Markdown file to a styled PDF. Uses the MarkdownHTMLExtractor for parsing, StyleManager for HTML/CSS rendering, and WeasyPrint for PDF export. Example:

  docskin md --input README.md --output README.pdf --css-style assets/minimal.css
  

• md-dir Recursively converts all Markdown files in a directory (and subdirectories) to PDFs, preserving the folder structure. Example:

  docskin md-dir --input ./docs --output ./pdfs --css-style assets/markdown-dark.css
  

• github Fetches a GitHub issue and converts it to a styled PDF. Supports custom API endpoints and authentication for private repos. Example:

  docskin github --repo owner/repo --issue 42 --output issue-42.pdf --css-style assets/markdown-dark.css
  

---

💡 Notes

• GitHub APIs use .netrc for authentication (if private repos).
• For Bosch internal: Use --api-base https://github.boschdevcloud.com/api/v3

📜 License and Third-Party Software

docskin is licensed under the MIT License – see LICENSE.txt for details.

This software uses WeasyPrint for PDF rendering.
WeasyPrint is licensed under the BSD 3-Clause License, and depends on system libraries such as Cairo, Pango, HarfBuzz, GDK-Pixbuf, and GLib, which are licensed under the LGPL or MIT licenses.

Some CSS files in assets/ are adapted from
sindresorhus/github-markdown-css,
which is licensed under the MIT License.

The file assets/github.svg.png is adapted from Primer Octicons, which is licensed under the MIT License.

The full license texts for docskin and the bundled third-party components are included in the LICENSE.txt file in this repository.

�️ Updated File Structure

docskin/
├── cli.py                # CLI entry point (Click commands: setup, md, md-dir, github)
├── converter.py          # MarkdownHTMLExtractor, MarkdownPdfRenderer, orchestration
├── github_api.py         # GitHub issue fetching
├── styles.py             # StyleManager: CSS loading & HTML rendering
├── setup.py              # Dependency installation logic
assets/
├── markdown-dark.css     # GitHub Dark Theme CSS [3rd party](https://github.com/sindresorhus/github-markdown-css)
├── markdown-light.css    # GitHub Light Theme CSS [3rd party](https://github.com/sindresorhus/github-markdown-css)
├── minimal.css           # Minimal light theme CSS
tests/
├── resources/
│   ├── markdown/         # Test Markdown files
├── test_cli.py           # CLI integration tests

Architecture

The architecture of docskin is designed to be modular and extensible. The main components are:

• CLI: The command-line interface for user interaction.
• MarkdownHTMLExtractor: Extracts HTML from Markdown files.
• StyleManager: Manages CSS styles and applies them to the HTML.
• PDFExporter: Handles the conversion of styled HTML to PDF.
• GitHubIssueFetcher: Fetches GitHub issues for conversion.

🧜 Mermaid Diagram Support

docskin automatically renders Mermaid diagrams embedded in Markdown files. Write standard fenced code blocks tagged mermaid and the diagrams will appear as crisp SVG graphics in the output PDF:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do it]
    B -->|No| D[Skip it]
```

Supported diagram types include flowcharts, sequence diagrams, class diagrams, Gantt charts, and all other types supported by the mermaid.ink rendering service.

Note: Diagram rendering requires an internet connection to reach https://mermaid.ink. When the service is unreachable the diagram source is preserved as a plain-text <pre> block so the rest of the document still renders correctly.

🛠️ TODO / Ideas

• PDF metadata (author, title, etc.)
• Generate TOC
• Bundle multiple issues
• Integrate Highlight.js

---

Made with ❤️ by a senior engineer passionate about open source.