fix: Fix dependencies. Improve docs (#18)

Author: javierbrea

components/cspell-config/dictionaries/tech.txt

@@ -2,3 +2,4 @@ automerge
 cacheable
 frontmatter
 nrwl
+syncrc

components/markdown-confluence-sync/CHANGELOG.md

@@ -11,7 +11,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 #### Deprecated
 #### Removed
 
-## [1.0.0-beta.1]
+## [1.0.0-beta.2] - 2024-11-26
+
+### Added
+
+* feat: Log possible error when trying to parse a markdown file
+* docs: Add markdown frontmatter examples
+* docs: Add examples of supported config files
+* docs: Add link to Confluence Sync documentation
+
+### Fixed
+
+* fix: Fix missed dependencies that were defined as devDependencies
+* fix: Add missing supported configuration options to TypeScript typings
+
+## [1.0.0-beta.1] [YANKED]
 
 ### Added
 

components/markdown-confluence-sync/README.md

@@ -51,14 +51,28 @@ In order to be able to sync the markdown files with Confluence, you need to have
 
 ### Compatibility
 
-> [!WARNING]
+> [!IMPORTANT]
 > This library has been tested only with Confluence 8.5.x. It may work with other versions, but it has not been tested.
 
 ## Features
 
 The library reads the markdown files in a given folder and create/delete/update the corresponding Confluence pages following the same hierarchical structure under a provided Confluence page depending on the [synchronization mode](#sync-modes) to use.
 
-Markdown documents to be synced __must have a `title` property, and a `sync_to_confluence` property set to `true` in the [frontmatter metadata](https://jekyllrb.com/docs/front-matter/).__
+> [!IMPORTANT]
+> Markdown documents to be synced __must have [frontmatter metadata](https://jekyllrb.com/docs/front-matter/)__ with at least next properties:
+> * `title` property, used to give a title to the page in Confluence.
+> * `sync_to_confluence` property set to `true`
+
+```markdown
+---
+title: Page title
+sync_to_confluence: true
+---
+
+# Page content
+
+Hello, world! I'm a markdown file to be synced with Confluence.
+```
 
 The library has __two modes for syncing__:
 * `tree` sync mode - Mirrors the hierarchical pages structure from given folder under a Confluence root page. Some files are used for [representing indices in the hierarchy](#index-files).
@@ -102,6 +116,19 @@ The library provides an NPM binary named `markdown-confluence-sync`. To use it,
 }
 ```
 
+All the markdown files to be synced must have frontmatter properties "title" and "sync_to_confluence" set to `true`. For example:
+
+```markdown
+---
+title: Page title
+sync_to_confluence: true
+---
+
+# Page content
+
+Hello, world! I'm a markdown file to be synced with Confluence.
+```
+
 As a starting point, you can create a `markdown-confluence-sync.config.js` file in the root of your project with the following content (read the [Configuration](#configuration) section for more information and other configuration methods):
 
 ```js title="markdown-confluence-sync.config.js"
@@ -196,6 +223,9 @@ repository/
 └── package.json
 ```
 
+> [!TIP]
+> You can also read the [Confluence Sync package documentation](https://github.com/Telefonica/cross-confluence-tools/tree/main/components/confluence-sync) for further info about the process of syncing to Confluence.
+
 ### Flat mode
 
 The `flat` mode syncs all markdown files matching a [glob pattern](https://github.com/isaacs/node-glob#glob-primer) just under the root Confluence page. It does not create a nested hierarchy.
@@ -247,10 +277,19 @@ The namespace for the configuration of this library is `markdown-confluence-sync
 
 ### Configuration file
 
-As mentioned above, the library supports defining the config in a configuration file. It supports many patterns for naming the file, as well as file formats. Read the [`@mocks-server/config` package](https://github.com/mocks-server/main/tree/master/packages/config) for further info about the supported patterns and formats. Just take into account that the namespace for the configuration is `markdown-confluence-sync`, so, a possible configuration file may be named `markdown-confluence-sync.config.js`. 
+As mentioned above, the library supports defining the config in a configuration file. It supports [many patterns for naming the file, as well as file formats](https://github.com/mocks-server/main/tree/master/packages/config#configuration-sources).
+
+Just take into account that the namespace for the configuration is `markdown-confluence-sync`, so, possible configuration files may be:
+
+* `markdown-confluence-sync.config.js`.
+* `.markdown-confluence-syncrc.yaml`.
+* `.markdown-confluence-syncrc.json`.
+
+> [!TIP]
+> Read the [`@mocks-server/config` docs](https://github.com/mocks-server/main/tree/master/packages/config#configuration-sources) for further info about all supported file names and formats of the configuration file.
 
 ```js title="markdown-confluence-sync.config.js"
-export default {
+module.exports = {
   docsDir: "docs",
   confluence: {
     url: "https://my-confluence.es",

components/markdown-confluence-sync/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tid-xcut/markdown-confluence-sync",
   "description": "Creates/updates/deletes Confluence pages based on markdown files in a directory. Supports Mermaid diagrams and per-page configuration using frontmatter metadata. Works great with Docusaurus",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "license": "Apache-2.0",
   "author": "Telefónica Innovación Digital",
   "repository": {
@@ -71,12 +71,15 @@
     "@mocks-server/logger": "2.0.0-beta.2",
     "@tid-xcut/confluence-sync": "workspace:*",
     "fs-extra": "11.2.0",
+    "glob": "10.3.10",
     "handlebars": "4.7.8",
     "hast": "1.0.0",
     "hast-util-to-string": "2.0.0",
     "mdast-util-mdx": "3.0.0",
     "mdast-util-mdx-jsx": "3.1.3",
     "mdast-util-to-markdown": "2.1.1",
+    "rehype": "12.0.1",
+    "rehype-parse": "8.0.5",
     "rehype-raw": "5.1.0",
     "rehype-stringify": "9.0.4",
     "remark": "14.0.3",
@@ -116,10 +119,6 @@
     "@types/which": "3.0.4",
     "babel-plugin-transform-import-meta": "2.2.1",
     "cross-fetch": "4.0.0",
-    "glob": "10.3.10",
-    "rehype": "12.0.1",
-    "rehype-parse": "8.0.5",
-    "remark-stringify": "10.0.3",
     "start-server-and-test": "2.0.8",
     "tmp": "0.2.3",
     "ts-dedent": "2.2.0",

components/markdown-confluence-sync/src/lib/confluence/ConfluenceSync.types.ts

@@ -33,6 +33,12 @@ declare global {
         spaceKey?: SpaceKeyOptionValue;
         /** Confluence root page id */
         rootPageId?: RootPageIdOptionValue;
+        /** Customize Confluence page titles by adding a prefix to all of them for improved organization and clarity */
+        rootPageName?: RootPageNameOptionValue;
+        /** Notice message to add at the beginning of the Confluence pages */
+        noticeMessage?: NoticeMessageOptionValue;
+        /** Template string to use for the notice message. */
+        noticeTemplate?: NoticeTemplateOptionValue;
         /** Confluence dry run */
         dryRun?: DryRunOptionValue;
       };

components/markdown-confluence-sync/src/lib/docusaurus/pages/DocusaurusDocPage.ts

@@ -35,8 +35,11 @@ export const DocusaurusDocPage: DocusaurusDocPageConstructor = class DocusaurusD
   implements DocusaurusDocPageInterface
 {
   protected _vFile: VFile;
+  protected _logger?: LoggerInterface;
 
   constructor(path: string, options?: DocusaurusDocPageOptions) {
+    this._logger = options?.logger;
+
     if (!existsSync(join(path))) {
       throw new PathNotExistException(`Path ${path} does not exist`);
     }
@@ -49,6 +52,7 @@ export const DocusaurusDocPage: DocusaurusDocPageConstructor = class DocusaurusD
     try {
       this._vFile = this._parseFile(path, options);
     } catch (e) {
+      this._logger?.error((e as Error).toString());
       throw new InvalidMarkdownFormatException(
         `Invalid markdown format: ${path}`,
         { cause: e },