Update documentation and samples

README.md

@@ -118,7 +118,7 @@ Alternatively, use the `--generated-by GENERATED_BY` option. The tag takes prece
 You execute the command-line tool `md2conf` to synchronize the Markdown file with Confluence:
 
 ```sh
-$ python3 -m md2conf sample/example.md
+$ python3 -m md2conf sample/index.md
 ```
 
 Use the `--help` switch to get a full list of supported command-line options:

integration_tests/test_api.py

@@ -31,7 +31,7 @@ def setUp(self) -> None:
         test_dir = Path(__file__).parent
         parent_dir = test_dir.parent
 
-        self.out_dir = test_dir / "tests" / "output"
+        self.out_dir = test_dir / "output"
         self.sample_dir = parent_dir / "sample"
         os.makedirs(self.out_dir, exist_ok=True)
 
@@ -40,7 +40,7 @@ def tearDown(self) -> None:
 
     def test_markdown(self) -> None:
         document = ConfluenceDocument(
-            self.sample_dir / "example.md",
+            self.sample_dir / "index.md",
             ConfluenceDocumentOptions(ignore_invalid_url=True),
             {},
         )
@@ -93,13 +93,13 @@ def test_synchronize(self) -> None:
         with ConfluenceAPI() as api:
             Application(
                 api, ConfluenceDocumentOptions(ignore_invalid_url=True)
-            ).synchronize(self.sample_dir / "example.md")
+            ).synchronize(self.sample_dir / "index.md")
 
     def test_synchronize_page(self) -> None:
         with ConfluenceAPI() as api:
             Application(
                 api, ConfluenceDocumentOptions(ignore_invalid_url=True)
-            ).synchronize_page(self.sample_dir / "example.md")
+            ).synchronize_page(self.sample_dir / "index.md")
 
     def test_synchronize_directory(self) -> None:
         with ConfluenceAPI() as api:

md2conf/properties.py

@@ -48,5 +48,3 @@ def __init__(
         self.user_name = opt_user_name
         self.api_key = opt_api_key
         self.space_key = opt_space_key
-        self.space_key = opt_space_key
-        self.space_key = opt_space_key

sample/example.md → sample/index.md

@@ -109,7 +109,7 @@ dignissim finibus dui.
 
 ## Admonitions
 
-Markdown has no native support for admonitions. Admonitions that follow the [Python-Markdown syntax](https://python-markdown.github.io/extensions/admonition/) are converted into Confluence structured macros, which are shown as info panels.
+Markdown has no native support for admonitions. Admonitions that follow the [Python-Markdown syntax](https://python-markdown.github.io/extensions/admonition/) are converted into Confluence structured macros, which are shown as info panels. (See [Alerts](#alerts) for an alternative that has pretty output in both GitHub and Confluence.)
 
 !!! info
     This is an information panel.
@@ -128,6 +128,25 @@ Markdown has no native support for admonitions. Admonitions that follow the [Pyt
 !!! warning "A warning message"
     This is a structured macro panel showing a warning.
 
+## Alerts
+
+[Alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) are a Markdown extension based on the blockquote syntax that you can use to emphasize critical information. On GitHub, they are displayed with distinctive colors and icons to indicate the significance of the content. When converted to Confluence, they are represented as structured macros, which are displayed as info panels.
+
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+
 ## Collapsed sections
 
 The [GitHub-specific](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections) formatting tag `<details>` that produces a collapsed section block is converted into the Confluence structured macro *expand* with a similar appearance. Behind the scenes, *md2conf* uses [Markdown in HTML](https://python-markdown.github.io/extensions/md_in_html/) to parse the content of the `<details>` element as Markdown, which is why you must always include the attribute `markdown="1"` on `<details>`:

sample/parent/child.md

@@ -1 +1,9 @@
+<!-- confluence-page-id: 86269493445 -->
+
+If you are a user who wants to publish pages to Confluence, you should install the package [markdown-to-confluence](https://pypi.org/project/markdown-to-confluence/) from PyPI. If you are a developer who wants to contribute, you should clone the repository [md2conf](https://github.com/hunyadi/md2conf) from GitHub.
+
 A child page without an explicitly assigned Confluence page ID or space key.
+
+When exporting a directory hierarchy, these pages inherit a parent page ID, and the page will show up as a child page of its parent in Confluence's space overview.
+
+When a child page without an explicit page ID is encountered, a Confluence page is automatically created, and its page ID is saved in the preamble of the Markdown document wrapped in a comment. Subsequently, synchronization will use the assigned page ID, and future changes to the parent/child relationship (e.g. moving the child page) will not be reflected.

sample/sibling.md

@@ -10,4 +10,4 @@ description: >
 
 If you are a user who wants to publish pages to Confluence, you should install the package [markdown-to-confluence](https://pypi.org/project/markdown-to-confluence/) from PyPI. If you are a developer who wants to contribute, you should clone the repository [md2conf](https://github.com/hunyadi/md2conf) from GitHub.
 
-This is a Markdown file in the same directory as the [sample document](example.md). This document is meant to illustrate how pages can refer to each other via [relative URLs](example.md#Basic-features).
+This is a Markdown file in the same directory as the [sample document](index.md). This document is meant to illustrate how pages can refer to each other via [relative URLs](index.md#Basic-features).

tests/test_processor.py

@@ -41,7 +41,7 @@ def test_process_document(self) -> None:
         )
         Processor(options, properties).process(self.sample_dir / "code.md")
 
-        self.assertTrue((self.sample_dir / "example.csf").exists())
+        self.assertTrue((self.sample_dir / "index.csf").exists())
 
     def test_process_directory(self) -> None:
         options = ConfluenceDocumentOptions(
@@ -55,7 +55,7 @@ def test_process_directory(self) -> None:
         )
         Processor(options, properties).process(self.sample_dir)
 
-        self.assertTrue((self.sample_dir / "example.csf").exists())
+        self.assertTrue((self.sample_dir / "index.csf").exists())
         self.assertTrue((self.sample_dir / "sibling.csf").exists())
         self.assertTrue((self.sample_dir / "code.csf").exists())