tgdoc

Rust CLI that converts Telegram ecosystem documentation into structured, Obsidian-compatible Markdown. Every internal cross-reference becomes a [[wiki-link]] pointing to the correct file and heading.

Sources

Configured in sources.toml. Currently two sources:

id	driver	parser	What it produces
tg-bot-api	http	tg-html	Scrapes core.telegram.org - Bot API reference, changelog, guides
ptb	git	ptb	Clones python-telegram-bot repo - class/method docs, changelog

Output structure

docs/
  tg-bot-api/
    api/
      index.md
      available-types.md
      available-methods.md
      getting-updates.md
      ...
    changelog/
      index.md
      2026/
        index.md
        BotAPI-9.5.md
      2025/
        ...
    webapps/
    payments-guide/
    bots.md
    faq.md
    inline.md
    webhooks.md
    ...

  ptb/
    index.md
    telegram/
      Bot.md
      Message.md
      Chat.md
      ...
    telegram/ext/
      Application.md
      CommandHandler.md
      Filters.md
      ...
    telegram/request/
      BaseRequest.md
      HTTPXRequest.md
    changelog/
      index.md
      2026/
        v22.7.md
        v22.6.md
      2025/
        ...
      2017/
        ...

Each file has YAML frontmatter with title, source, tags, and (for changelog entries) date.

Usage

# Fetch all sources
just fetch

# Fetch a single source
just fetch tg-bot-api
just fetch ptb

# Dry-run - print structure without writing files
just dry
just dry ptb

# Clean and re-fetch
just refetch

# Pack docs/ into a timestamped tar.gz
just pack

# Fetch then pack
just all

# Remove docs/ and archives
just clean

Or directly via cargo:

cargo run --release -- fetch --config sources.toml --out docs
cargo run --release -- fetch tg-bot-api --dry

sources.toml

[[source]]
id     = "tg-bot-api"
driver = "http"
parser = "tg-html"
out    = "tg-bot-api"

[source.http]
base_url = "https://core.telegram.org"
proxy    = "http://127.0.0.1:8580"   # optional

[[source]]
id     = "ptb"
driver = "git"
parser = "ptb"
out    = "ptb"

[source.git]
repo = "https://github.com/python-telegram-bot/python-telegram-bot"
ref  = "master"

Adding a new source requires: a sources.toml entry, a src/source/<name>.rs file implementing run(cfg, raw, out_dir, dry), and a line in src/source/mod.rs.

How links work

tg-bot-api: two-pass HTML scrape. First pass builds an anchor index (#sendMessage -> [[tg-bot-api/api/available-methods#sendMessage]]). Second pass converts every <a href> through the index.

ptb: anchor index is built from parsed class and method names (bot.send_message -> [[ptb/telegram/Bot#send_message]]). RST :class: and :meth: directives in docstrings are resolved through the same index, producing cross-links between sources where possible.

Drivers

driver	behaviour
http	reqwest + optional proxy, gzip. Fetches URLs defined by the parser.
git	git clone --depth 1 on first run, git pull on subsequent runs. Clone stored in repos/<id>/ (gitignored).

Releases

# Tag and push - triggers GitHub Actions to build x86_64 + aarch64 binaries
just tag-release          # tags v<version in Cargo.toml>
just tag-release 1.1.0    # bumps Cargo.toml, commits, then tags

# Re-trigger an existing tag
just retag

Installation

Download a release archive from the Releases page. Each archive contains:

tgdoc           # binary
sources.toml    # source configuration
justfile        # convenience recipes
README.md

Extract and run from the same directory:

tar -xzf tgdoc-x86_64-unknown-linux-gnu.tar.gz
./tgdoc fetch

tgdoc looks for sources.toml in this order:

1. Path passed via --config <path>
2. sources.toml in the current working directory
3. sources.toml next to the binary

So running from the extracted directory works out of the box. If you move the binary to $PATH, either keep sources.toml in your working directory or always pass --config /path/to/sources.toml.

Notes

• docs/, repos/, and *.tar.gz are gitignored
• tg-bot-api requires a proxy to reach core.telegram.org
• ptb clones from GitHub directly (no proxy needed)