From 0682f92aa8425e4e3905c56046e111f65a48c00e Mon Sep 17 00:00:00 2001 From: Levente Hunyadi Date: Tue, 24 Sep 2024 08:53:55 +0200 Subject: [PATCH] Update documentation and samples --- README.md | 2 +- integration_tests/test_api.py | 8 ++++---- md2conf/properties.py | 2 -- sample/{example.md => index.md} | 21 ++++++++++++++++++++- sample/parent/child.md | 8 ++++++++ sample/sibling.md | 2 +- tests/test_processor.py | 4 ++-- 7 files changed, 36 insertions(+), 11 deletions(-) rename sample/{example.md => index.md} (84%) diff --git a/README.md b/README.md index 38a3451..acf1f2b 100644 --- a/README.md +++ b/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: diff --git a/integration_tests/test_api.py b/integration_tests/test_api.py index ade3194..79bb56a 100644 --- a/integration_tests/test_api.py +++ b/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: diff --git a/md2conf/properties.py b/md2conf/properties.py index 22e4ce5..af3a77c 100644 --- a/md2conf/properties.py +++ b/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 diff --git a/sample/example.md b/sample/index.md similarity index 84% rename from sample/example.md rename to sample/index.md index f1890a2..096ebf2 100644 --- a/sample/example.md +++ b/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 `
` 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 `
` element as Markdown, which is why you must always include the attribute `markdown="1"` on `
`: diff --git a/sample/parent/child.md b/sample/parent/child.md index 0b0d1a2..55cb7e5 100644 --- a/sample/parent/child.md +++ b/sample/parent/child.md @@ -1 +1,9 @@ + + +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. diff --git a/sample/sibling.md b/sample/sibling.md index 4c75dee..f57e7a0 100644 --- a/sample/sibling.md +++ b/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). diff --git a/tests/test_processor.py b/tests/test_processor.py index a77aa98..f633a6d 100644 --- a/tests/test_processor.py +++ b/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())