gospelo-backlog-docs 1.0.0

Upload Markdown documents to Backlog Wiki with image and MermaidJS support

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.

---

Features

• Upload Markdown files to Backlog Wiki
• 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)

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 a Markdown file

gospelo-backlog-docs document.md --project PROJECT_KEY

Usage

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

Arguments

Argument	Description
markdown_file	Path to the Markdown file to upload
--project, -p	Backlog project key (required)
--wiki-name, -n	Wiki page name (defaults to H1 title or filename)
--space-id, -s	Backlog space ID
--api-key, -k	Backlog API key
--domain, -d	Backlog domain (default: backlog.jp)
--env-file, -e	Path to .env file
--dry-run	Parse only, do not upload
--version, -v	Show version

Examples

# Basic upload
gospelo-backlog-docs docs/design.md --project MYPROJECT

# Specify wiki page name
gospelo-backlog-docs docs/design.md --project MYPROJECT --wiki-name "Design/UI Spec"

# 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.