Gospelo Backlog Docs

Overview

Upload Markdown documents to Backlog Wiki with image and MermaidJS support.

The Story Behind

One day in a development team's Slack channel:

Engineer: "Where can I find the specs for this function?" Client: "In the head of Tanaka-san, who left the company last month."

The engineer looked up to the heavens and cried out:

"Dear God, save me from this documentation-less hell!"

At that moment, there seemed to be a divine revelation:

(Make it yourself.)

"...Fine. I'll build it. Automatically."

And thus, Gospelo was born.

A documentation tool for engineers that delivers "words of salvation" to the documentation wasteland and helps the "specs are in my head" guy finally find peace.

The name "gospel" + "pelo" came from a late-night coding session where the developer thought "I felt like God told me to make it myself, so I did (・ω<)☆". Issues about naming sense are not accepted.

"Gospel" means "good news" or "words of salvation" in Christianity.

What's New in v1.1.0

• Directory batch processing - Upload all Markdown files from a directory at once
• Progress display - Animated spinner with percentage and progress bar
• New options: --no-recursive, --pattern, --exclude, --continue-on-error

See Changelog for full details.

Features

• Upload Markdown files to Backlog Wiki
• Batch upload from directories with recursive search
• Automatic image upload and link conversion
• MermaidJS diagram conversion to PNG (requires mermaid-cli)
• Extract wiki page name from H1 title
• Support for hierarchical wiki page names (e.g., Parent/Child/Page)
• Flexible credential management (CLI args, environment variables, .env files)
• Progress display with spinner and percentage

Installation

pip install gospelo-backlog-docs

Optional: MermaidJS Support

To enable MermaidJS diagram conversion, install mermaid-cli:

npm install -g @mermaid-js/mermaid-cli

Quick Start

1. Set up credentials

Create a .env file or set environment variables:

# .env
BACKLOG_SPACE_ID=your-space-id
BACKLOG_API_KEY=your-api-key
BACKLOG_DOMAIN=backlog.jp  # or backlog.com

Or use the global config directory:

mkdir -p ~/.config/gospelo-backlog-docs
cp .env.example ~/.config/gospelo-backlog-docs/.env
# Edit the file with your credentials

2. Upload Markdown files

# Single file
gospelo-backlog-docs document.md --project PROJECT_KEY

# All files in a directory (recursive)
gospelo-backlog-docs docs/ --project PROJECT_KEY

Usage

gospelo-backlog-docs <path> --project <PROJECT_KEY> [options]

Arguments

Examples

# Upload a single file
gospelo-backlog-docs docs/design.md --project MYPROJECT

# Specify wiki page name (single file only)
gospelo-backlog-docs docs/design.md --project MYPROJECT --wiki-name "Design/UI Spec"

# Upload all Markdown files in a directory (recursive)
gospelo-backlog-docs docs/ --project MYPROJECT

# Upload only top-level files (no subdirectories)
gospelo-backlog-docs docs/ --project MYPROJECT --no-recursive

# Upload only spec files
gospelo-backlog-docs docs/ --project MYPROJECT --pattern "*_spec.md"

# Exclude README and draft files
gospelo-backlog-docs docs/ --project MYPROJECT --exclude "README.md" --exclude "*_draft.md"

# Continue uploading even if some files fail
gospelo-backlog-docs docs/ --project MYPROJECT --continue-on-error

# Dry run (parse without uploading)
gospelo-backlog-docs docs/design.md --project MYPROJECT --dry-run

# Use specific .env file
gospelo-backlog-docs docs/design.md --project MYPROJECT --env-file .env.production

Credential Priority

Credentials are resolved in the following order (highest priority first):

1. CLI arguments (--space-id, --api-key, --domain)
2. Environment variables (BACKLOG_SPACE_ID, BACKLOG_API_KEY, BACKLOG_DOMAIN)
3. Specified .env file (--env-file)
4. Local .env file (current directory)
5. Global config ~/.config/gospelo-backlog-docs/.env

Markdown Features

Images

Local images are automatically uploaded:

![Screenshot](./images/screenshot.png)

External URLs are preserved as-is:

![Logo](https://example.com/logo.png)

MermaidJS Diagrams

MermaidJS code blocks are converted to PNG images (requires mermaid-cli):

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
```

Wiki Page Name

The wiki page name is determined by:

1. --wiki-name argument (if specified)
2. First H1 title in the Markdown file
3. Filename (without extension)

Hierarchical names are supported:

# Parent/Child/Page Name

Requirements

• Python 3.10+
• requests
• python-dotenv
• mermaid-cli (optional, for MermaidJS support)

Documentation

• Japanese README
• Changelog
• Contributing Guide
• Test Report

License

MIT License - see LICENSE for details.

Third-Party Licenses

See THIRD_PARTY_LICENSES.md for dependency licenses.