md-confluence-cli 5.6.3 → 5.6.4

package/README.md

@@ -4,38 +4,150 @@
 
 ## Pull Commands
 
-Pull pages from Confluence to your local machine as markdown files.
+The `pull` command allows you to download Confluence pages as markdown files to your local machine. This is useful for:
+
+- **Backup documentation** from Confluence
+- **Work offline** with local markdown files
+- **Migrate documentation** between Confluence spaces
+- **Version control** documentation changes
+- **Edit and republish** pages locally
 
 ### Pull a Single Page
 
+Pull a single Confluence page by its page ID:
+
 ```bash
-# Pull a specific page by ID
+# Pull a page to default directory (./pulled-pages)
 npx md-confluence-cli@latest pull 123456789
 
 # Pull to a specific directory
 npx md-confluence-cli@latest pull 123456789 --output ./docs
+
+# Pull with overwrite existing files
+npx md-confluence-cli@latest pull 123456789 --output ./docs --overwrite
 ```
 
 ### Pull a Page Tree (Recursive)
 
+Pull a page and all its children recursively to create a complete documentation tree:
+
 ```bash
-# Pull a page and all its children recursively
+# Pull a page and all children recursively (default max-depth: 10)
 npx md-confluence-cli@latest pull 123456789 --recursive
 
-# Limit recursion depth (default: 10)
+# Pull with custom output directory
+npx md-confluence-cli@latest pull 123456789 --output ./docs --recursive
+
+# Limit recursion depth (useful for large page trees)
 npx md-confluence-cli@latest pull 123456789 --recursive --max-depth 5
 ```
 
-### Additional Options
+### Pull Command Options
+
+| Option | Alias | Type | Default | Description |
+|--------|-------|------|---------|-------------|
+| `--output` | `-o` | string | `./pulled-pages` | Output directory for markdown files |
+| `--recursive` | `-r` | boolean | `false` | Pull page and all children recursively |
+| `--max-depth` | - | number | `10` | Maximum recursion depth when using `--recursive` |
+| `--overwrite` | `-w` | boolean | `false` | Overwrite existing files |
+| `--file-name-template` | `-t` | string | `{title}.md` | Template for filename generation |
+
+### Pulled File Structure
+
+When pulling pages with `--recursive`, the CLI creates a nested folder structure that mirrors the Confluence page hierarchy:
+
+```
+docs/
+├── frontend/
+│   ├── index.md              # Root page (has children)
+│   ├── mobile_app/
+│   │   ├── index.md          # Page with children
+│   │   ├── app_info.md      # Page without children
+│   │   └── adjust_tracking_install_and_more.md
+│   ├── launch_game.md        # Page without children
+│   └── fe_integration_credentials.md
+```
+
+**Structure Rules:**
+- **Pages with children** → Saved as `index.md` inside a folder named after the page title
+- **Pages without children** → Saved as `{title}.md` in the parent folder
+- **Nested hierarchy** → Maintains the exact parent-child relationships from Confluence
+
+### Pulled File Frontmatter
+
+Each pulled markdown file includes comprehensive frontmatter with Confluence metadata:
+
+```yaml
+---
+pageId: 123456789
+title: "Page Title"
+spaceKey: S5
+version: 3
+lastUpdated: "712020:0aa84074-41f8-442b-b137-ac2d5bd53315"
+pulledAt: "2025-11-04T10:07:13.904Z"
+confluenceUrl: "https://s5philippines.atlassian.net/pages/viewpage.action?pageId=123456789"
+parentId: 987654321
+---
+```
+
+**Frontmatter Fields:**
+- `pageId` - Confluence page ID (used for republishing)
+- `title` - Page title from Confluence
+- `spaceKey` - Confluence space key
+- `version` - Current page version number
+- `lastUpdated` - Last update timestamp
+- `pulledAt` - When the page was pulled locally
+- `confluenceUrl` - Direct link to the Confluence page
+- `parentId` - Parent page ID (for hierarchy)
+
+### Publishing Pulled Pages
 
+Pulled pages can be republished back to Confluence. The `pageId` in frontmatter ensures pages are updated (not duplicated):
+
+```bash
+# After pulling and editing locally
+npx md-confluence-cli@latest publish "docs/frontend/index.md"
+```
+
+**Important Notes:**
+- Pages with `pageId` in frontmatter will **update** existing Confluence pages
+- Pages without `pageId` will **create new** pages
+- The `connie-publish: true` frontmatter flag controls whether a page should be published
+
+### Pull Examples
+
+**Example 1: Pull entire documentation tree**
+```bash
+# Pull the "Frontend" documentation tree
+npx md-confluence-cli@latest pull 46923777 --output ./docs --recursive
+```
+
+**Example 2: Pull single page for editing**
 ```bash
-# Overwrite existing files
-npx md-confluence-cli@latest pull 123 --overwrite
+# Pull a specific page to edit locally
+npx md-confluence-cli@latest pull 94732294 --output ./docs
+```
 
-# Custom filename template
+**Example 3: Pull with custom filename**
+```bash
+# Use custom filename template
 npx md-confluence-cli@latest pull 123 --file-name-template "{id}_{title}.md"
 ```
 
+**Example 4: Pull shallow tree (only 2 levels deep)**
+```bash
+# Limit depth for large documentation trees
+npx md-confluence-cli@latest pull 46923777 --recursive --max-depth 2 --output ./docs
+```
+
+### Pull Best Practices
+
+- **Use `--output`** to organize pulled pages into your project structure
+- **Use `--max-depth`** when pulling large page trees to avoid excessive downloads
+- **Use `--overwrite`** carefully - it will replace existing local files
+- **Review frontmatter** after pulling to ensure `pageId` is correct for republishing
+- **Test locally** before republishing pulled pages to avoid overwriting Confluence content
+
 ## Usage Examples
 
 ### CLI
@@ -69,10 +181,17 @@ set ATLASSIAN_API_TOKEN="YOUR API TOKEN"
 
 [Learn more about `set` command](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/set_1)
 
-**CLI Command**
+**CLI Commands**
 
 ```bash
+# Publish markdown files to Confluence (default command)
 npx md-confluence-cli
+
+# Pull a single page from Confluence
+npx md-confluence-cli pull <pageId>
+
+# Pull a page tree recursively
+npx md-confluence-cli pull <pageId> --recursive --output ./docs
 ```
 
 ### Docker Container

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "md-confluence-cli",
-    "version": "5.6.3",
+    "version": "5.6.4",
     "description": "This CLI allows you to publish your notes to Confluence",
     "bin": "dist/index.js",
     "scripts": {
@@ -19,8 +19,8 @@
         "confluence.js": "^1.6.3",
         "boxen": "7.1.1",
         "chalk": "5.3.0",
-        "md-confluence-lib": "5.6.3",
-        "md-confluence-mermaid-puppeteer-renderer": "5.6.3"
+        "md-confluence-lib": "5.6.4",
+        "md-confluence-mermaid-puppeteer-renderer": "5.6.4"
     },
     "dependencies": {
         "yargs": "^17.7.2"