Upload Workflow¶

Upload converts your local Markdown files into Confluence Storage Format (XHTML) and publishes them as pages in your Confluence space.

Basic Upload¶

BashPowerShellCMD

dotnet run --project src/ConfluenceSynkMD -- \
  --mode Upload \
  --path ./docs \
  --conf-space DEV \
  --conf-parent-id 12345

dotnet run --project src/ConfluenceSynkMD -- `
  --mode Upload `
  --path ./docs `
  --conf-space DEV `
  --conf-parent-id 12345

dotnet run --project src/ConfluenceSynkMD -- ^
  --mode Upload ^
  --path .\docs ^
  --conf-space DEV ^
  --conf-parent-id 12345

This uploads all .md files from ./docs as child pages under page 12345 in space DEV.

Docker Upload¶

BashPowerShellCMD

```bash
docker run --rm -it \
    -e CONFLUENCE__BASEURL=https://yoursite.atlassian.net \
    -e CONFLUENCE__AUTHMODE=Basic \
    -e CONFLUENCE__USEREMAIL=user@example.com \
    -e CONFLUENCE__APITOKEN=your-token \
    -v ${PWD}:/workspace \
    confluencesynkmd \
    --mode Upload \
    --path /workspace/docs \
    --conf-space DEV \
    --conf-parent-id 12345
```

Path Hint

Keep -v ${PWD}:/workspace unchanged.
Only change the --path suffix (for example /workspace/docs).
${PWD} is your current local directory.

```powershell
docker run --rm -it `
    -e CONFLUENCE__BASEURL=https://yoursite.atlassian.net `
    -e CONFLUENCE__AUTHMODE=Basic `
    -e CONFLUENCE__USEREMAIL=user@example.com `
    -e CONFLUENCE__APITOKEN=your-token `
    -v ${PWD}:/workspace `
    confluencesynkmd `
    --mode Upload `
    --path /workspace/docs `
    --conf-space DEV `
    --conf-parent-id 12345
```

Path Hint

Keep -v ${PWD}:/workspace unchanged.
Only change the --path suffix (for example /workspace/docs).
${PWD} is your current local directory.

```cmd
docker run --rm -it ^
    -e CONFLUENCE__BASEURL=https://yoursite.atlassian.net ^
    -e CONFLUENCE__AUTHMODE=Basic ^
    -e CONFLUENCE__USEREMAIL=user@example.com ^
    -e CONFLUENCE__APITOKEN=your-token ^
    -v %cd%:/workspace ^
    confluencesynkmd ^
    --mode Upload ^
    --path /workspace/docs ^
    --conf-space DEV ^
    --conf-parent-id 12345
```

Path Hint

Keep -v %cd%:/workspace unchanged.
Only change the --path suffix (for example /workspace/docs).
%cd% is your current local directory.

Hierarchical Upload¶

By default, ConfluenceSynkMD preserves your local directory structure as a parent–child page tree in Confluence (--keep-hierarchy is true by default).

docs/
├── getting-started.md      → Child of parent page
├── guides/
│   ├── setup.md            → Child of "guides" index page
│   └── advanced.md         → Child of "guides" index page
└── api/
    └── endpoints.md        → Child of "api" index page

To flatten all pages under the root (disable hierarchy):

BashPowerShellCMD

--skip-hierarchy

--skip-hierarchy

--skip-hierarchy

Using a Root Page¶

Instead of --conf-parent-id, you can specify a root page by title. If the page doesn't exist, it will be created:

BashPowerShellCMD

dotnet run --project src/ConfluenceSynkMD -- \
  --mode Upload \
  --path ./docs \
  --conf-space DEV \
  --root-page "My Documentation"

dotnet run --project src/ConfluenceSynkMD -- `
  --mode Upload `
  --path ./docs `
  --conf-space DEV `
  --root-page "My Documentation"

dotnet run --project src/ConfluenceSynkMD -- ^
  --mode Upload ^
  --path .\docs ^
  --conf-space DEV ^
  --root-page "My Documentation"

Skip Unchanged Pages¶

Use --skip-update to avoid re-uploading pages whose content hasn't changed. ConfluenceSynkMD computes content hashes to detect changes:

BashPowerShellCMD

--skip-update

--skip-update

--skip-update

This significantly speeds up repeated uploads of large documentation sets.

Page Title Prefix¶

Add a prefix to all uploaded page titles (useful for distinguishing auto-generated content):

BashPowerShellCMD

--title-prefix "[AUTO] "

--title-prefix "[AUTO] "

--title-prefix "[AUTO] "

This produces page titles like [AUTO] Getting Started, [AUTO] Setup Guide, etc.

Generated-By Marker¶

By default, ConfluenceSynkMD adds a generated-by info macro at the top of each page. You can customize or disable this:

BashPowerShellCMD

# Custom template with file path placeholder
--generated-by "Auto-generated from %{filepath}"

# Disable the marker entirely
--generated-by ""

# Custom template with file path placeholder
--generated-by "Auto-generated from %{filepath}"

# Disable the marker entirely
--generated-by ""

REM Custom template with file path placeholder
--generated-by "Auto-generated from %{filepath}"

REM Disable the marker entirely
--generated-by ""

Supported placeholders: %{filepath}, %{filename}, %{filedir}, %{filestem}.

Page-ID Write-Back¶

After upload, ConfluenceSynkMD writes Confluence Page IDs back into your Markdown source files as HTML comments:

<!-- confluence-page-id: 12345 -->
<!-- confluence-space-key: DEV -->

This enables round-trip sync — subsequent uploads will update the existing page rather than creating a new one. To disable:

BashPowerShellCMD

--no-write-back

--no-write-back

--no-write-back

Debug Mode¶

For troubleshooting conversion issues, enable debug line markers:

BashPowerShellCMD

--debug-line-markers --loglevel debug

--debug-line-markers --loglevel debug

--debug-line-markers --loglevel debug

This includes source line numbers in error messages, making it easier to locate issues in your Markdown files.