You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
All notable changes to this project will be documented in this file.
@@ -16,6 +11,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
16
11
#### Deprecated
17
12
#### Removed
18
13
14
+
## [1.1.0] - 2025-01-29
15
+
16
+
### Added
17
+
18
+
* feat: Add `files-metadata` input. It allows the user to provide a JSON array with the metadata of the files to be synchronized. This way, the user can set the Confluence id, title, etc. without the need to add frontmatter to the markdown files.
19
+
* feat: Support `id` mode. It allows the user to provide a list of files to be synchronized only by their Confluence id.
20
+
21
+
### Changed
22
+
23
+
* chore(deps): Bump @tid-xcut/markdown-confluence-sync from 1.0.0 to 1.1.0 (Add id mode and filesMetadata option)
Copy file name to clipboardExpand all lines: README.md
+49-15Lines changed: 49 additions & 15 deletions
Original file line number
Diff line number
Diff line change
@@ -1,9 +1,3 @@
1
-
---
2
-
sync_to_confluence: true
3
-
title: "[Markdown Confluence Sync] Github action"
4
-
confluence_page_id: "337906332"
5
-
---
6
-
7
1
# Markdown Confluence Sync action
8
2
9
3
This action syncs markdown files to Confluence using the [Markdown Confluence Sync](https://github.com/Telefonica/cross-confluence-tools/tree/main/components/markdown-confluence-sync) library.
@@ -16,6 +10,7 @@ This action syncs markdown files to Confluence using the [Markdown Confluence Sy
16
10
-[Markdown files to sync](#markdown-files-to-sync)
17
11
-[Tree operation mode](#tree-operation-mode)
18
12
-[Flat operation mode](#flat-operation-mode)
13
+
-[Id operation mode](#id-operation-mode)
19
14
-[Configuration](#configuration)
20
15
-[Inputs](#inputs)
21
16
-[Configuration file](#configuration-file)
@@ -30,19 +25,19 @@ This action syncs markdown files to Confluence using the [Markdown Confluence Sy
30
25
* Supports Mermaid diagrams
31
26
* Per-page configuration using [frontmatter metadata](https://jekyllrb.com/docs/front-matter/)
32
27
* Works great with [Docusaurus](https://docusaurus.io/)
33
-
*Two modes of operation:
28
+
*Three modes of operation:
34
29
***tree**: Mirrors the hierarchical pages structure from given folder under a Confluence root page
35
-
***flat**: Synchronize a list of markdown files matched by a [glob pattern](https://github.com/isaacs/node-glob#glob-primer)as children page of a Confluence root page, without any hierarchy.
36
-
* As an extra in this mode, a Confluence id can be provided to each page using frontmatter, and, in such case, the corresponding Confluence page will be updated, no matter if it is a child of the root page or not.
37
-
30
+
***id**: Synchronize a list of markdown files matched by a [glob pattern](https://github.com/isaacs/node-glob#glob-primer)directly to specific Confluence pages using the Confluence id provided in the frontmatter metadata or in the configuration file.
31
+
***flat**: Synchronize a list of markdown files matched by a [glob pattern](https://github.com/isaacs/node-glob#glob-primer) as children page of a Confluence root page, without any hierarchy. It is also possible to provide a Confluence id to some pages to update them directly, as in the id mode.
32
+
38
33
> [!NOTE]
39
34
> Read the [Markdown Confluence Sync library documentation](https://github.com/Telefonica/cross-confluence-tools/tree/main/components/markdown-confluence-sync) for detailed information about all features and configuration options.
40
35
41
36
## Usage
42
37
43
38
### Markdown files to sync
44
39
45
-
First of all, your markdown files must have a frontmatter metadata block at the beginning of the file. This metadata block must be in YAML format and must contain at least the `title` and the `sync_to_confluence` fields. The `sync_to_confluence` field must be set to `true` to indicate that the page should be synchronized with Confluence.
40
+
All the markdown files to be synced must have frontmatter properties "title" and "sync_to_confluence" set to true (unless you are using the `files-metadata` option). For example:
46
41
47
42
```markdown
48
43
---
@@ -81,11 +76,49 @@ docs/
81
76
> [!TIP]
82
77
> Read the [tree mode docs](https://github.com/Telefonica/cross-confluence-tools/tree/main/components/markdown-confluence-sync#tree-mode) for further information about configuration options and how to organize your markdown files.
83
78
79
+
### Id operation mode
80
+
81
+
If you want to update only specific pages directly by providing their id, you can use the id mode. In this mode, you don't need to provide a root page id. Each page in the list must have an id, and the library will update the corresponding Confluence page having the id provided. Note that the pages to update must exist in Confluence before running the sync process.
82
+
83
+
This mode is very useful when you want to update only a few pages, such as the README.md or the CHANGELOG.md files.
84
+
85
+
> [!TIP]
86
+
> Use the `files-metadata` option to provide the data of the files to sync without having to modify the markdown files themselves.
You should use __flat__ mode in case your markdown files are not organized in a hierarchical structure and you want to synchronize all of them as children of a Confluence root page.
87
120
88
-
As an extra in this mode, a Confluence id can be provided to each page using frontmatter, and, in such case, the corresponding Confluence page will be updated, no matter if it is a child of the root page or not.
121
+
As an extra in this mode, a Confluence id can be provided to some pages, as in the "id mode", to update them directly.
89
122
90
123
For example:
91
124
@@ -124,9 +157,10 @@ The action accepts a configuration file in the root of the repository, and it ca
124
157
125
158
| Name | Description | Required | Default |
126
159
|------|-------------|----------|---------|
127
-
| `mode` | Operation mode: `tree` or `flat` | No | `tree` |
160
+
| `mode` | Operation mode: `tree`, `id` or `flat` | No | `tree` |
128
161
| `docs-dir` | Path to the directory containing the markdown files | __Yes__ | |
129
-
| `files-pattern` | Pattern to filter the files to sync in flat mode | No | |
162
+
| `files-metadata` | Array of objects with the metadata of the files to sync, expressed as an stringified JSON (supports multiline). Each object must have at least the `path` property for identifying the file. For the rest of properties read the [markdown-confluence-sync docs](https://github.com/Telefonica/cross-confluence-tools/tree/main/components/markdown-confluence-sync#filesmetadata-property) | No | |
163
+
| `files-pattern` | Pattern to filter the files to sync in flat or id mode | No | |
130
164
| `confluence-url` | Confluence base URL | __Yes__ | |
131
165
| `confluence-root-page-id` | ID of the Confluence page under which the pages will be synchronized | __Yes__ | |
132
166
| `confluence-space-key` | Key of the Confluence space where the pages will be synced | __Yes__ | |
@@ -160,7 +194,7 @@ module.exports = {
160
194
}
161
195
```
162
196
163
-
> [!INFO]
197
+
> [!NOTE]
164
198
> Read the [Markdown Confluence Sync library docs](https://github.com/Telefonica/cross-confluence-tools/tree/main/components/markdown-confluence-sync#configuration-file) for further info about the configuration file.
0 commit comments