### Manage development lifecycle with npm

Source: https://github.com/7nohe/confluence-md/blob/main/docs/README.md

Standard npm commands to install dependencies, start the development server, and build the project for production deployment.

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview
```

--------------------------------

### Install Dependencies

Source: https://github.com/7nohe/confluence-md/blob/main/CONTRIBUTING.md

Run this command in your terminal to install all necessary project dependencies.

```bash
npm install
```

--------------------------------

### Install project dependencies

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Install all required project dependencies using npm.

```bash
# Install dependencies
npm install
```

--------------------------------

### Full GitHub Action Input Example

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/inputs.mdx

An example demonstrating the usage of all available input parameters for the confluence-md GitHub Action, including required and optional settings.

```yaml
- uses: daiki/confluence-md@v1
  with:
    # Required
    confluence_base_url: ${{ vars.CONFLUENCE_BASE_URL }}
    email: ${{ secrets.CONFLUENCE_EMAIL }}
    api_token: ${{ secrets.CONFLUENCE_API_TOKEN }}
    source: docs/README.md

    # Page configuration
    page_id: '123456789'
    frontmatter_page_id_key: confluence_page_id
    title_override: 'Documentation'

    # Image handling
    attachments_base: 'assets/'
    image_mode: upload
    download_remote_images: 'true'

    # Behavior
    skip_if_unchanged: 'true'
    dry_run: 'false'
    notify_watchers: 'false'

    # Advanced
    user_agent: my-custom-agent

```

--------------------------------

### Commit Message Examples

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Common examples of commit messages following the project's convention.

```bash
# Feature
git commit -m "feat: add support for nested lists"

# Bug fix
git commit -m "fix: escape special characters in code blocks"

# Documentation
git commit -m "docs: update installation instructions"

# Breaking change
git commit -m "feat!: require Node.js 20+"
```

--------------------------------

### Install act on macOS

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Use Homebrew to install the act tool for running GitHub Actions locally.

```bash
brew install act
```

--------------------------------

### Identify Confluence Page ID from URL

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/getting-started/installation.mdx

Example demonstrating how to extract the unique numeric page ID from a standard Confluence URL structure.

```text
https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/123456789/Page+Title
                                                       ^^^^^^^^^
                                                       This is the page ID
```

--------------------------------

### Initialize Development Environment

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/development/contributing.mdx

Commands to clone the repository and install necessary project dependencies using npm.

```bash
git clone https://github.com/daiki/confluence-md.git
cd confluence-md
npm install
```

--------------------------------

### Accessing Confluence Action Outputs

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/getting-started/quick-start.mdx

Demonstrates how to capture and use outputs from the confluence-md action, such as the page URL, update status, and version, for subsequent workflow steps.

```yaml
- uses: daiki/confluence-md@v1
  id: confluence
  with:
    confluence_base_url: ${{ vars.CONFLUENCE_BASE_URL }}
    email: ${{ secrets.CONFLUENCE_EMAIL }}
    api_token: ${{ secrets.CONFLUENCE_API_TOKEN }}
    source: docs/README.md

- name: Show Results
  run: |
    echo "Page URL: ${{ steps.confluence.outputs.page_url }}"
    echo "Updated: ${{ steps.confluence.outputs.updated }}"
    echo "Version: ${{ steps.confluence.outputs.version }}"
```

--------------------------------

### Configure GitHub Actions Workflow for Confluence Sync

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/getting-started/quick-start.mdx

Sets up a CI/CD pipeline using the confluence-md action to automate the synchronization of Markdown files to Confluence on push events. Requires base URL, email, and API token secrets.

```yaml
name: Sync to Confluence

on:
  push:
    branches: [main]
    paths:
      - 'docs/**/*.md'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: daiki/confluence-md@v1
        with:
          confluence_base_url: ${{ vars.CONFLUENCE_BASE_URL }}
          email: ${{ secrets.CONFLUENCE_EMAIL }}
          api_token: ${{ secrets.CONFLUENCE_API_TOKEN }}
          source: docs/README.md
```

--------------------------------

### JavaScript Function Example

Source: https://github.com/7nohe/confluence-md/blob/main/tests/fixtures/sample.md

A simple JavaScript function that takes a name as input and logs a greeting to the console. This snippet demonstrates basic function definition and console output in JavaScript.

```javascript
function greet(name) {
  console.log(`Hello, ${name}!`);
}
```

--------------------------------

### Mermaid Graph Example

Source: https://github.com/7nohe/confluence-md/blob/main/tests/fixtures/sample.md

A basic flowchart diagram defined using Mermaid syntax. This snippet illustrates how to create directed graphs with nodes and connections, commonly used for visualizing processes or structures.

```mermaid
graph TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[OK]
    B -->|No| D[End]
```

--------------------------------

### Define Markdown Frontmatter for Confluence Sync

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/getting-started/quick-start.mdx

Configures a Markdown file with the required confluence_page_id in the frontmatter. This ID tells the action which specific Confluence page to update.

```markdown
---
confluence_page_id: 123456789
---

# My Documentation

This content will be synced to Confluence.

## Features

- **Bold** and *italic* text
- Code blocks with syntax highlighting
- Tables and lists
```

--------------------------------

### Configure sidebar translations

Source: https://github.com/7nohe/confluence-md/blob/main/docs/README.md

How to define sidebar navigation labels with internationalization support within the astro.config.mjs file.

```javascript
sidebar: [
  {
    label: 'Getting Started',
    translations: { ja: 'はじめに' },
    autogenerate: { directory: 'getting-started' },
  },
]
```

--------------------------------

### Mermaid Diagram Syntax Examples

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/mermaid.mdx

A collection of supported Mermaid diagram types including Flowcharts, Sequence, Class, State, Gantt, and Entity Relationship diagrams for use within Markdown files.

```markdown
```mermaid
flowchart LR
    A --> B --> C
```

```mermaid
sequenceDiagram
    Alice->>Bob: Hello
    Bob-->>Alice: Hi!
```

```mermaid
classDiagram
    Animal <|-- Dog
    Animal <|-- Cat
```

```mermaid
stateDiagram-v2
    [*] --> Active
    Active --> Inactive
    Inactive --> [*]
```

```mermaid
gantt
    title Project Timeline
    section Phase 1
    Task 1: 2024-01-01, 30d
    Task 2: 2024-01-15, 20d
```

```mermaid
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
```
```

--------------------------------

### Configure GitHub Actions Workflow for Confluence Sync

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/getting-started/installation.mdx

This YAML configuration defines a GitHub Action workflow that triggers on pushes to the main branch. It uses the confluence-md action to sync Markdown files to a specified Confluence instance using stored secrets for authentication.

```yaml
name: Sync to Confluence

on:
  push:
    branches: [main]
    paths:
      - 'docs/**/*.md'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: daiki/confluence-md@v1
        with:
          confluence_base_url: https://your-domain.atlassian.net
          email: ${{ secrets.CONFLUENCE_EMAIL }}
          api_token: ${{ secrets.CONFLUENCE_API_TOKEN }}
          source: docs/README.md
```

--------------------------------

### Define MDX page frontmatter

Source: https://github.com/7nohe/confluence-md/blob/main/docs/README.md

The required frontmatter structure for new documentation pages in the src/content/docs/ directory.

```mdx
---
title: My New Page
description: A brief description of this page.
---

# Content goes here
```

--------------------------------

### Posting Slack Notification on Confluence Update (YAML)

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/outputs.mdx

An example of integrating the Confluence action with Slack notifications. A Slack message is sent only if the Confluence page was updated, using the `page_url` output.

```yaml
- uses: daiki/confluence-md@v1
  id: confluence
  with:
    # ... inputs

- name: Notify Slack
  if: steps.confluence.outputs.updated == 'true'
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {
        "text": "Documentation updated: ${{ steps.confluence.outputs.page_url }}"
      }
```

--------------------------------

### CLI Options Reference

Source: https://github.com/7nohe/confluence-md/blob/main/README.md

List of available command-line arguments for configuring the synchronization process.

```text
-u, --url <url>            Confluence base URL (or CONFLUENCE_BASE_URL env)
-e, --email <email>        Confluence account email (or CONFLUENCE_EMAIL env)
-p, --page-id <id>         Confluence page ID (or use frontmatter)
-s, --space-key <key>      Confluence space key (creates new page if no page_id)
--parent-page-id <id>      Parent page ID for new pages
--no-write-page-id         Disable writing created page ID back to frontmatter
--title <title>            Override page title
--attachments-base <path>  Base directory for resolving image paths
--image-mode <mode>        Image handling: upload or external (default: upload)
--download-remote-images   Download remote images as attachments
--mermaid-macro <name>     Macro name for mermaid fences (match your Confluence Mermaid app)
--exclude <patterns>       Glob patterns to exclude files (comma-separated)
--no-skip-unchanged        Update even if content unchanged
--dry-run                  Preview without updating Confluence
--json                     Output results as JSON
-v, --verbose              Enable verbose output
-c, --config <path>        Path to config file
```

--------------------------------

### Project Build and Development Commands

Source: https://github.com/7nohe/confluence-md/blob/main/AGENTS.md

Commands for building the project, running tests, linting, and testing the CLI locally.

```bash
# Build (bundles Action to dist/, CLI to dist/cli/)
npm run build

# Run tests
npm test

# Run single test file
npx vitest run tests/converter.test.ts

# Run tests in watch mode
npm run test:watch

# Lint & Format (Biome)
npm run check          # Check only
npm run check:fix      # Auto-fix

# Type checking
npm run typecheck

# Run all CI checks locally
npm run ci

# Test CLI locally
export CONFLUENCE_API_TOKEN="your-token"
node dist/cli/index.js docs/page.md --url https://example.atlassian.net --email you@example.com --dry-run

# Test with act (requires Docker)
act push                                                    # Full CI
act -j test-action -W .github/workflows/test-action.yml     # Test action
```

--------------------------------

### Build project components

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Commands to build the GitHub Action, the CLI, or both simultaneously.

```bash
# Build both GitHub Action and CLI
npm run build

# GitHub Action only
npm run build:action

# CLI only
npm run build:cli
```

--------------------------------

### Run Development Commands

Source: https://github.com/7nohe/confluence-md/blob/main/CONTRIBUTING.md

Execute these commands for testing, code checking, type checking, and building the project during development.

```bash
npm run test
```

```bash
npm run check
```

```bash
npm run typecheck
```

```bash
npm run build
```

--------------------------------

### Configure GitHub Action

Source: https://github.com/7nohe/confluence-md/blob/main/README.md

Automate documentation publishing using a GitHub Actions workflow file.

```yaml
name: Publish docs
on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: 7nohe/confluence-md@v0.2.2
        with:
          confluence_base_url: https://example.atlassian.net
          email: you@example.com
          api_token: ${{ secrets.CONFLUENCE_API_TOKEN }}
          source: docs/
          # Optional: create pages for files without a page ID
          space_key: DOCS
```

--------------------------------

### Run CI checks

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Execute the full CI pipeline including linting, type checking, testing, and building.

```bash
# Runs Biome → TypeCheck → Test → Build sequentially
npm run ci
```

--------------------------------

### Run tests

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Execute the test suite using vitest, with options for watch mode or targeting specific files and tests.

```bash
# Run tests
npm test

# Watch mode
npm run test:watch

# Specific test file
npx vitest run tests/converter.test.ts

# Specific test name
npx vitest run -t "should convert h1"
```

--------------------------------

### List available workflows

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Displays all workflows available for execution via act.

```bash
act --list
```

--------------------------------

### Project directory structure

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Overview of the source code and test file organization.

```text
src/
├── main.ts           # GitHub Action entry point
├── cli.ts            # CLI entry point
├── core.ts           # Shared logic
├── inputs.ts         # Input parameter handling
├── frontmatter.ts    # YAML frontmatter parsing
├── logger.ts         # Logging abstraction
├── types.ts          # Type definitions
├── images.ts         # Image processing
├── converter/        # Markdown → Confluence conversion
│   ├── index.ts      # Conversion pipeline
│   ├── nodes.ts      # AST node converters
│   └── xml.ts        # XML utilities
└── confluence/       # Confluence API
    ├── client.ts     # HTTP client
    ├── pages.ts      # Page operations
    └── attachments.ts # Attachment operations

tests/                # Test files
test-fixtures/        # Test data
dist/index.js         # Action bundle (committed; refreshed by the release workflow)
```

--------------------------------

### Run act with explicit architecture

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Overrides default configuration to force specific architecture and image settings, useful for M1/M2 Mac troubleshooting.

```bash
act push --container-architecture linux/amd64 -P ubuntu-latest=catthehacker/ubuntu:act-latest
```

--------------------------------

### Lint and format code

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Use Biome to check, fix, lint, or format the codebase.

```bash
# Check only
npm run check

# Auto-fix
npm run check:fix

# Lint only
npm run lint
npm run lint:fix

# Format only
npm run format
npm run format:fix
```

--------------------------------

### Configure .confluence.yml

Source: https://github.com/7nohe/confluence-md/blob/main/README.md

Define default settings in a YAML file located in the project root.

```yaml
confluence_base_url: https://example.atlassian.net
email: you@example.com
frontmatter_page_id_key: confluence_page_id
image_mode: upload
skip_if_unchanged: true
```

--------------------------------

### Auto-create Pages via CLI

Source: https://github.com/7nohe/confluence-md/blob/main/README.md

Create new pages in a specific space when a page ID is missing.

```bash
npx @7nohe/confluence-md docs/ \
  --url https://example.atlassian.net \
  --email you@example.com \
  --space-key DOCS
```

--------------------------------

### Run confluence-md via CLI

Source: https://github.com/7nohe/confluence-md/blob/main/README.md

Execute synchronization tasks using npx. Requires the CONFLUENCE_API_TOKEN environment variable to be set.

```bash
# Set API token as environment variable (required)
export CONFLUENCE_API_TOKEN="your-api-token"

# Basic usage
npx @7nohe/confluence-md docs/page.md \
  --url https://example.atlassian.net \
  --email you@example.com

# With page ID specified
npx @7nohe/confluence-md docs/page.md \
  --url https://example.atlassian.net \
  --email you@example.com \
  --page-id 123456

# Dry run (preview without updating)
npx @7nohe/confluence-md docs/page.md --dry-run

# JSON output for scripting
npx @7nohe/confluence-md docs/page.md --json

# Directory sync (page IDs must be defined in frontmatter)
npx @7nohe/confluence-md docs/ \
  --url https://example.atlassian.net \
  --email you@example.com

# Short alias
cfmd docs/page.md --dry-run
```

--------------------------------

### Run CI workflows

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Executes the full CI pipeline or specific jobs like linting, type checking, testing, or building.

```bash
# Run all jobs
act push

# Run specific job
act -j lint       # Biome check
act -j typecheck  # Type check
act -j test       # Tests
act -j build      # Build
```

--------------------------------

### Build Project Bundle

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/development/architecture.mdx

Uses @vercel/ncc to bundle the TypeScript source code and all dependencies into a single executable file located in the dist directory.

```bash
npm run build
```

--------------------------------

### Configure act settings

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

The .actrc file defines default container architecture and image mappings for local workflow execution.

```text
--container-architecture linux/amd64
-P ubuntu-latest=catthehacker/ubuntu:act-latest
```

--------------------------------

### Run type check

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Execute TypeScript type checking for the project.

```bash
npm run typecheck
```

--------------------------------

### Display Hello Message in JavaScript

Source: https://github.com/7nohe/confluence-md/blob/main/test-fixtures/sample.md

A simple function to log a greeting to the console. This serves as a basic demonstration of JavaScript syntax within the project documentation.

```javascript
function hello() {
  console.log('Hello, Confluence!');
}
```

--------------------------------

### Define Frontmatter for Directory Sync

Source: https://github.com/7nohe/confluence-md/blob/main/README.md

Markdown files must include a page ID in the frontmatter to be tracked during directory synchronization.

```markdown
---
confluence_page_id: 123456
---

# Page title
```

--------------------------------

### Test the action in dry-run mode

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Executes the test-action workflow without making actual Confluence API calls.

```bash
act -j test-action -W .github/workflows/test-action.yml
```

--------------------------------

### Frontmatter vs Action Input for Page ID Priority

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/frontmatter.mdx

Explains the priority between specifying the Confluence page ID via frontmatter and as an action input. Frontmatter has higher priority, meaning it will be used if present. The action input serves as a fallback only when frontmatter is missing. This is useful for syncing multiple files to the same page.

```yaml
- uses: daiki/confluence-md@v1
  with:
    # ... other inputs
    page_id: '123456789'  # Used only if frontmatter is missing
    source: docs/README.md
```

--------------------------------

### Run Specific Vitest Test

Source: https://github.com/7nohe/confluence-md/blob/main/AGENTS.md

Execute a specific test case by name using Vitest.

```bash
npx vitest run -t "should convert h1"
```

--------------------------------

### Conventional Commit Format

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

The standard structure for commit messages used in this project.

```text
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

--------------------------------

### Manage Environment Variables and Secrets

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/basic-usage.mdx

Shows the recommended pattern for separating non-sensitive configuration (using variables) from sensitive credentials (using secrets).

```yaml
- uses: daiki/confluence-md@v1
  with:
    confluence_base_url: ${{ vars.CONFLUENCE_BASE_URL }}
    email: ${{ secrets.CONFLUENCE_EMAIL }}
    api_token: ${{ secrets.CONFLUENCE_API_TOKEN }}
    source: docs/README.md
```

--------------------------------

### Define Frontmatter Page ID and Title

Source: https://github.com/7nohe/confluence-md/blob/main/README.md

Specify page ID and custom title within the Markdown frontmatter.

```markdown
---
confluence_page_id: 123456
title: My Confluence Page
---

# Page title
```

--------------------------------

### Adding Confluence Sync Results to GitHub Step Summary (YAML)

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/outputs.mdx

Illustrates how to append Confluence synchronization results to the GitHub Actions step summary. This uses several outputs from the daiki/confluence-md action to provide a concise report.

```yaml
- uses: daiki/confluence-md@v1
  id: confluence
  with:
    # ... inputs

- name: Add Summary
  run: |
    echo "## Confluence Sync Results" >> $GITHUB_STEP_SUMMARY
    echo "- **Page**: [${{ steps.confluence.outputs.page_id }}](${{ steps.confluence.outputs.page_url }})" >> $GITHUB_STEP_SUMMARY
    echo "- **Updated**: ${{ steps.confluence.outputs.updated }}" >> $GITHUB_STEP_SUMMARY
    echo "- **Version**: ${{ steps.confluence.outputs.version }}" >> $GITHUB_STEP_SUMMARY
```

--------------------------------

### Prune Docker system

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Cleans up unused Docker data to resolve disk space issues.

```bash
docker system prune -af --volumes
```

--------------------------------

### Markdown Local Images to Confluence XML

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/conversion-rules.mdx

Converts Markdown image syntax for local files into Confluence's `ac:image` with an `ri:attachment` element.

```markdown
![Alt text](./image.png)
```

```xml
<ac:image>
  <ri:attachment ri:filename="image.png"/>
</ac:image>
```

--------------------------------

### GitHub Action Workflow - Confluence MD Conversion

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/index.mdx

This YAML snippet demonstrates how to use the daiki/confluence-md GitHub Action in a workflow. It specifies the Confluence base URL, user credentials (email and API token stored as secrets), and the source Markdown file path. This action automates the conversion and update of Confluence pages.

```yaml
- uses: daiki/confluence-md@v1
  with:
    confluence_base_url: https://your-domain.atlassian.net
    email: ${{ secrets.CONFLUENCE_EMAIL }}
    api_token: ${{ secrets.CONFLUENCE_API_TOKEN }}
    source: docs/README.md
```

--------------------------------

### Lint and Format Code

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/development/contributing.mdx

Commands to check code quality and automatically apply formatting using Biome.

```bash
npm run check
npm run format
```

--------------------------------

### Execute Test Suite

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/development/contributing.mdx

Commands to run tests using Vitest, including running all tests, specific files, or using watch mode.

```bash
npm test
npx vitest run tests/converter.test.ts
npx vitest run -t "should convert h1"
npm run test:watch
```

--------------------------------

### Dry Run Mode

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/inputs.mdx

Enabling 'dry_run' converts Markdown to Confluence format and outputs the result without making API calls or uploading attachments. This is useful for testing configurations.

```yaml
dry_run: 'false'
```

--------------------------------

### Confluence Base URL Configuration

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/inputs.mdx

Specifies the base URL for your Confluence Cloud instance. It must include the protocol (e.g., 'https://'). Trailing slashes are automatically handled.

```yaml
confluence_base_url: https://your-company.atlassian.net
```

--------------------------------

### Skip If Unchanged Behavior

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/inputs.mdx

When enabled ('true'), the action compares content hashes to avoid unnecessary updates. This prevents duplicate versions and notifications if the content hasn't changed.

```yaml
skip_if_unchanged: 'true'
```

--------------------------------

### Configure custom base directory for attachments

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/images.mdx

Use the attachments_base input to define a root directory for resolving local image paths.

```yaml
- uses: daiki/confluence-md@v1
  with:
    source: docs/guide.md
    attachments_base: 'assets/'
```

--------------------------------

### Sync Multiple Files via Matrix Strategy

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/basic-usage.mdx

Utilizes a GitHub Actions matrix strategy to synchronize multiple Markdown files to Confluence in parallel. This approach is ideal for projects with documentation spread across several files.

```yaml
jobs:
  sync:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        file:
          - docs/guide.md
          - docs/api.md
          - docs/faq.md
    steps:
      - uses: actions/checkout@v4
      - uses: daiki/confluence-md@v1
        with:
          confluence_base_url: ${{ vars.CONFLUENCE_BASE_URL }}
          email: ${{ secrets.CONFLUENCE_EMAIL }}
          api_token: ${{ secrets.CONFLUENCE_API_TOKEN }}
          source: ${{ matrix.file }}
```

--------------------------------

### Markdown Task Lists to Confluence XML

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/conversion-rules.mdx

Markdown task lists are rendered as plain text within `<li>` tags as Confluence lacks native checkbox support.

```markdown
- [ ] Todo item
- [x] Completed item
```

```xml
<ul>
  <li>[ ] Todo item</li>
  <li>[x] Completed item</li>
</ul>
```

--------------------------------

### Accessing Confluence Action Outputs in GitHub Workflows (YAML)

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/outputs.mdx

Demonstrates how to access and utilize the various outputs provided by the daiki/confluence-md action within a GitHub Actions workflow. Outputs are accessed using the step's ID and the specific output name.

```yaml
steps:
  - uses: daiki/confluence-md@v1
    id: confluence
    with:
      confluence_base_url: ${{ vars.CONFLUENCE_BASE_URL }}
      email: ${{ secrets.CONFLUENCE_EMAIL }}
      api_token: ${{ secrets.CONFLUENCE_API_TOKEN }}
      source: docs/README.md

  - name: Display Results
    run: |
      echo "Page URL: ${{ steps.confluence.outputs.page_url }}"
      echo "Page ID: ${{ steps.confluence.outputs.page_id }}"
      echo "Version: ${{ steps.confluence.outputs.version }}"
      echo "Updated: ${{ steps.confluence.outputs.updated }}"
      echo "Attachments: ${{ steps.confluence.outputs.attachments_uploaded }}"
      echo "Content Hash: ${{ steps.confluence.outputs.content_hash }}"
```

--------------------------------

### Enable remote image downloading

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/images.mdx

Configure the action to download remote images and attach them to the Confluence page to prevent link rot.

```yaml
download_remote_images: 'true'
```

--------------------------------

### Basic Frontmatter for Confluence Page ID

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/frontmatter.mdx

Demonstrates the basic usage of YAML frontmatter to specify the Confluence page ID. The frontmatter must be enclosed in `---` delimiters at the beginning of the Markdown file. This is the primary method for mapping a Markdown file to a specific Confluence page.

```markdown
---
confluence_page_id: 123456789
---

# Your Content Here
```

--------------------------------

### Markdown Remote Images to Confluence XML

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/conversion-rules.mdx

Converts Markdown image syntax for remote URLs into Confluence's `ac:image` with an `ri:url` element.

```markdown
![Alt text](https://example.com/image.png)
```

```xml
<ac:image>
  <ri:url ri:value="https://example.com/image.png"/>
</ac:image>
```

--------------------------------

### Git Workflow Commands

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/development/contributing.mdx

Standard commands for creating feature branches and pushing changes to the repository.

```bash
git checkout -b feature/your-feature-name
git add .
git commit -m "Add your feature"
git push origin feature/your-feature-name
```

--------------------------------

### Markdown Paragraphs to Confluence XML

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/conversion-rules.mdx

Plain text paragraphs in Markdown are converted to `<p>` elements in Confluence storage format.

```markdown
This is a paragraph.

This is another paragraph.
```

```xml
<p>This is a paragraph.</p>
<p>This is another paragraph.</p>
```

--------------------------------

### Define Unit Tests

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/development/contributing.mdx

Standard structure for writing unit tests using the Vitest framework.

```typescript
import { describe, it, expect } from 'vitest';

describe('featureName', () => {
  it('should handle basic case', () => {
    const input = 'test';
    const result = yourFunction(input);
    expect(result).toBe('expected');
  });
});
```

--------------------------------

### Markdown Mermaid Diagrams to Confluence XML

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/conversion-rules.mdx

Converts Markdown code blocks with the 'mermaid' language identifier into Confluence's 'mermaid' structured macro.

```markdown
```mermaid
graph TD
    A --> B
```
```

```xml
<ac:structured-macro ac:name="mermaid">
  <ac:plain-text-body><![CDATA[graph TD
    A --> B]]></ac:plain-text-body>
</ac:structured-macro>
```

--------------------------------

### Reference local images in Markdown

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/images.mdx

Standard Markdown syntax for including local images. By default, paths are resolved relative to the Markdown file's directory.

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

--------------------------------

### Image Handling Mode

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/inputs.mdx

Determines how images are processed. 'upload' sends local images as attachments, while 'external' uses URLs, requiring local images to be externally accessible.

```yaml
image_mode: upload
```

--------------------------------

### Conditional Workflow Step Based on Confluence Update (YAML)

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/outputs.mdx

Shows how to conditionally execute a GitHub Actions step based on whether the Confluence page was updated. This uses the `updated` output from the daiki/confluence-md action.

```yaml
- name: Notify on Update
  if: steps.confluence.outputs.updated == 'true'
  run: echo "Page was updated!"
```

--------------------------------

### Including Multiple Metadata Fields in Frontmatter

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/frontmatter.mdx

Illustrates how to include various metadata fields within the YAML frontmatter, such as title, author, date, and tags. The `confluence-md` action specifically extracts the page ID key, while other fields can be used for other purposes or by different tools.

```markdown
---
title: My Documentation
author: John Doe
date: 2024-01-15
confluence_page_id: 123456789
tags:
  - documentation
  - api
---

# Content
```

--------------------------------

### Breaking Change Commit Syntax

Source: https://github.com/7nohe/confluence-md/blob/main/DEVELOPMENT.md

Syntax for indicating breaking changes that trigger a major version bump.

```bash
feat!: change API response format

# or

feat: change API response format

BREAKING CHANGE: The response format has changed from XML to JSON.
```

--------------------------------

### Markdown Headings to Confluence XML

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/conversion-rules.mdx

Converts Markdown headings (H1-H3) to corresponding HTML `<h1>`, `<h2>`, and `<h3>` tags.

```markdown
# Heading 1
## Heading 2
### Heading 3
```

```xml
<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3>
```

--------------------------------

### Markdown Links to Confluence XML

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/conversion-rules.mdx

Converts Markdown link syntax to an HTML `<a>` tag with the specified href.

```markdown
[Link text](https://example.com)
```

```xml
<a href="https://example.com">Link text</a>
```

--------------------------------

### Markdown Unordered Lists to Confluence XML

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/conversion-rules.mdx

Converts Markdown unordered lists, including nested items, to Confluence's `<ul>` and `<li>` structure.

```markdown
- Item 1
- Item 2
  - Nested item
```

```xml
<ul>
  <li>Item 1</li>
  <li>Item 2
    <ul>
      <li>Nested item</li>
    </ul>
  </li>
</ul>
```

--------------------------------

### Markdown Code Blocks to Confluence XML

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/conversion-rules.mdx

Converts standard Markdown code blocks, specifying the language, into Confluence's structured macro for code display.

```markdown
```javascript
function hello() {
  console.log("Hello!");
}
```
```

```xml
<ac:structured-macro ac:name="code">
  <ac:parameter ac:name="language">javascript</ac:parameter>
  <ac:plain-text-body><![CDATA[function hello() {
  console.log("Hello!");
}]]></ac:plain-text-body>
</ac:structured-macro>
```

--------------------------------

### Customizing Frontmatter Key for Confluence Page ID

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/frontmatter.mdx

Shows how to customize the frontmatter key used to identify the Confluence page ID. By default, 'confluence_page_id' is used, but this can be overridden using the 'frontmatter_page_id_key' input in the action. The corresponding key in the Markdown frontmatter must then be used.

```yaml
- uses: daiki/confluence-md@v1
  with:
    # ... other inputs
    frontmatter_page_id_key: 'page_id'
```

```markdown
---
page_id: 123456789
---

```

--------------------------------

### Markdown Ordered Lists to Confluence XML

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/conversion-rules.mdx

Converts Markdown ordered lists to Confluence's `ol` and `li` structure.

```markdown
1. First
2. Second
3. Third
```

```xml
<ol>
  <li>First</li>
  <li>Second</li>
  <li>Third</li>
</ol>
```

--------------------------------

### Convert Mermaid Markdown to Confluence XML Macro

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/mermaid.mdx

Demonstrates the transformation of a standard Markdown Mermaid code block into the XML structure required by the Confluence Mermaid Diagrams app. This process relies on the 'mermaid' language identifier in fenced code blocks.

```markdown
```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```
```

```xml
<ac:structured-macro ac:name="mermaid">
  <ac:plain-text-body><![CDATA[graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E]]></ac:plain-text-body>
</ac:structured-macro>
```

--------------------------------

### Markdown Special Characters Escaping

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/conversion-rules.mdx

Demonstrates how special characters like `<`, `>`, `&`, and `"` are escaped to their HTML entity equivalents in Confluence storage format.

```markdown
`<`
```

```markdown
`>`
```

```markdown
`&`
```

```markdown
`"`
```

```markdown
`&lt;`
```

```markdown
`&gt;`
```

```markdown
`&amp;`
```

```markdown
`&quot;`
```

--------------------------------

### Perform Dry Run Sync

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/basic-usage.mdx

Enables dry run mode to validate the generated Confluence storage format without performing actual API calls to update the remote page.

```yaml
- uses: daiki/confluence-md@v1
  with:
    confluence_base_url: ${{ vars.CONFLUENCE_BASE_URL }}
    email: ${{ secrets.CONFLUENCE_EMAIL }}
    api_token: ${{ secrets.CONFLUENCE_API_TOKEN }}
    source: docs/README.md
    dry_run: 'true'
```

--------------------------------

### Page ID Configuration

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/inputs.mdx

Sets the Confluence page ID for publishing content. This parameter acts as a fallback if the page ID is not found in the frontmatter.

```yaml
page_id: '123456789'
```

--------------------------------

### Configure Conditional Syncing

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/basic-usage.mdx

Restricts the execution of the sync workflow to only trigger when specific Markdown files within the documentation directory are modified.

```yaml
on:
  push:
    branches: [main]
    paths:
      - 'docs/**/*.md'
```

--------------------------------

### Markdown Blockquotes to Confluence XML

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/conversion-rules.mdx

Converts Markdown blockquotes, including multi-line content, into Confluence's `<blockquote>` element containing a `<p>` tag.

```markdown
> This is a quote
> spanning multiple lines
```

```xml
<blockquote>
  <p>This is a quote spanning multiple lines</p>
</blockquote>
```

--------------------------------

### Skip Unchanged Content

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/basic-usage.mdx

Configures the action to skip updates if the content hash matches the existing page, preventing unnecessary API requests.

```yaml
- uses: daiki/confluence-md@v1
  with:
    skip_if_unchanged: 'true'
```

--------------------------------

### Markdown Horizontal Rules to Confluence XML

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/conversion-rules.mdx

Converts Markdown horizontal rule syntax (`---`) to an HTML `<hr/>` tag.

```markdown
---

```

```xml
<hr/>
```

--------------------------------

### Override Page Title

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/basic-usage.mdx

Allows setting a custom title for the Confluence page directly from the workflow configuration, overriding the default behavior.

```yaml
- uses: daiki/confluence-md@v1
  with:
    title_override: 'My Custom Title'
```

--------------------------------

### Markdown Tables to Confluence XML

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/reference/conversion-rules.mdx

Converts Markdown tables into Confluence's `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, and `<td>` structure. Use `<br>` for line breaks within cells.

```markdown
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
```

```xml
<table>
  <thead>
    <tr>
      <th>Header 1</th>
      <th>Header 2</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Cell 1</td>
      <td>Cell 2</td>
    </tr>
  </tbody>
</table>
```

```markdown
| Header |
|--------|
| Line 1<br>Line 2 |
```

--------------------------------

### Set image processing mode

Source: https://github.com/7nohe/confluence-md/blob/main/docs/src/content/docs/guides/images.mdx

The image_mode input determines whether images are uploaded as attachments or referenced via external URLs.

```yaml
# Upload Mode (Default)
image_mode: 'upload'

# External Mode
image_mode: 'external'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.