Merge pull request #42 from iamjackg/develop

Adding a whole bunch of stuff

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install .
+          python -m pip install -e .
           python -m pip install -r requirements-test.txt
       - name: Test with pytest
         run: |

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+### Added
+- Support for labels in the Markdown front matter
+- Option to replace all labels with the set specified in the Markdown front matter
+- Option to add a postface to every page
+- Option to ignore `.gitignore` files (@bjorns)
+- Option to remove single newlines from paragraphs (@bjorns)
+### Changed
+- Skip files and directories listed in `.gitignore` files (@bjorns)
+
 ## 1.4.0 - 2022-07-27
 ### Added
 - Add option to remove the top level header from the page

README.md

@@ -1,18 +1,18 @@
 # md2cf
 
 A tool and library to convert documents written in Markdown to Confluence Storage
-format, and optionally upload them to a Confluence Server instance.
+format and upload them to a Confluence instance.
 
 ## Features
 
-  - **Convert Markdown documents.** The library implements a
+  - **Convert Markdown documents:** a library implementing a
     [Mistune](https://github.com/lepture/mistune) renderer that outputs
     Confluence Storage Format.
-  - **Basic Confluence API support.** Embedded micro-implementation of
+  - **Talk to the Confluence API:** an embedded micro-implementation of
     the [Confluence Server REST
     API](https://developer.atlassian.com/server/confluence/confluence-server-rest-api/)
     with basic support for creating and updating pages.
-  - **Upload automation.** Includes a small script that can automate the
+  - **Upload your documents automatically:** a full-featured command line utility that can automate the
     upload process for you.
 
 ## Installation
@@ -25,10 +25,13 @@ pip install md2cf
 
 ```text
 usage: md2cf [-h] [-o HOST] [-u USERNAME] [-p PASSWORD] [--token TOKEN]
-             [--insecure] -s SPACE [-a PARENT_TITLE | -A PARENT_ID] [-t TITLE]
-             [-m MESSAGE] [-i PAGE_ID] [--prefix PREFIX]
-             [--preface-markdown [PREFACE_MARKDOWN] | --preface-file
-             PREFACE_FILE] [--collapse-single-pages]
+             [--insecure] [-s SPACE] [-a PARENT_TITLE | -A PARENT_ID]
+             [-t TITLE] [-m MESSAGE] [-i PAGE_ID] [--prefix PREFIX]
+             [--strip-top-header] [--remove-text-newlines]
+             [--replace-all-labels] [--preface-markdown [PREFACE_MARKDOWN] |
+             --preface-file PREFACE_FILE]
+             [--postface-markdown [POSTFACE_MARKDOWN] | --postface-file
+             POSTFACE_FILE] [--collapse-single-pages] [--no-gitignore]
              [--beautify-folders | --use-pages-file]
              [--collapse-empty | --skip-empty] [--dry-run] [--only-changed]
              [file_list [file_list ...]]
@@ -37,14 +40,13 @@ usage: md2cf [-h] [-o HOST] [-u USERNAME] [-p PASSWORD] [--token TOKEN]
 In order to upload a document, you'll need to supply at least the
 following five parameters:
 
-  - The **hostname** of your Confluence instance, including the path to
+  - The **URL** of your Confluence instance, including the path to
     the REST API (e.g. `http://confluence.example.com/rest/api`)
   - Either
-    - The **username** and **password** to use for logging into the instance, or
+    - The **username** and **password** to log into the instance, or
     - a **personal access token**
   - The **space** in which to publish the page
-  - The **files or directories** to be uploaded -- or standard input if the list is
-    missing
+  - The **files or directories** to be uploaded -- if none are specified, the contents will be read from the standard input
 
 Example basic usage:
 
@@ -90,21 +92,57 @@ The **title** of the page can come from a few sources, in order of priority from
 
 Note that if you're reading from standard input, you must either specify the title through the command line or have a title in the content as a header or in the front matter.
 
-If you want to strip the top level header from the document, so the title isn't repeated in the body of the page, pass the `--`
+If you want to strip the top level header from the document, so the title isn't repeated in the body of the page, pass the `--strip-top-header` parameter.
 
 If you're uploading entire folders, you might want to add a prefix to each page title in order to avoid collisions. You can do this using the `--prefix` parameter.
 
-### Adding a preface
+### Removing extra newlines
 
-The `--preface-markdown` and `--preface-file` commands allow you to add some text at the top of each page. This is useful
-if you're mirroring documentation to Confluence and want people to know that it's going to be overwritten in an automated
-fashion.
+If your document uses single newlines to break lines, for example if it was typeset with a fixed column width, Confluence Cloud might respect those newlines and produce a document that's difficult to read. Use the `--remove-text-newlines` parameter to replace every newline within a paragraph with a space.
 
-The first option allows you to specify markdown text right on the command line, and defaults to a paragraph saying
+For example, this will turn
+
+```text
+This is a document
+with hardcoded newlines
+in its paragraphs.
+
+It's not that nice
+to read.
+```
+
+into
+
+```text
+This is a document with hardcoded newlines in its paragraphs.
+
+It's not that nice to read.
+```
+
+### Adding a preface and/or postface
+
+The `--preface-markdown`, `--preface-file`, `--postface-markdown`, and `--postface-file` commands allow you to add some text at the top or bottom of each page. This is useful  if you're mirroring documentation to Confluence and want people to know that it's going to be overwritten in an automated fashion.
+
+The first option allows you to specify Markdown text right on the command line. If you don't specify anything, it defaults to a paragraph saying
 
 **Contents are auto-generated, do not edit.**
 
-The second option takes a path to a markdown file and will prepend its contents to every page. Note that this is parsed separately and added to the body after the main page has been parsed, so it won't influence behaviour tied to the page contents such as title or front matter detection.
+The second option takes a path to a markdown file and will prepend or append its contents to every page. Note that this is parsed separately and added to the body after the main page has been parsed, so it won't influence behaviour tied to the page contents, such as title or front matter detection.
+
+### Page labels
+
+You can specify labels for your page by adding a `labels` entry in your document's front matter, i.e. a YAML block delimited by `---` lines at the top of the file
+
+```yaml
+  ---
+  labels:
+    - first label
+    - second label
+  ---
+  # Rest of the document here
+```
+
+By default, labels will only be added. If you want the final set of labels to _exactly_ match what you listed in the front matter, pass the `--replace-all-labels` option.
 
 ### Parent page
 
@@ -129,7 +167,11 @@ If you want to avoid redundant uploads (and the corresponding update emails) whe
 
 `md2cf` can upload entire folders for you. This can be useful if you want to mirror some in-repo documentation to Confluence.
 
-When uploading entire folders, `md2cf` will recursively traverse all subdirectories and upload any `.md` file it encounters. Folders will be represented by empty pages in the final upload, since Confluence can only nest pages under other pages. You can modify this behaviour through three command line parameters.
+When uploading entire folders, `md2cf` will recursively traverse all subdirectories and upload any `.md` file it encounters.
+
+By default, `md2cf` will honour your `.gitignore` and skip any files or folders it defines. If you want to avoid this, add the `--no-gitignore` option.
+
+Folders will be represented by empty pages in the final upload, since Confluence can only nest pages under other pages. You can modify this behaviour through three command line parameters.
 
 #### Customizing folder names
 
@@ -196,7 +238,7 @@ folderA/
     lonely-document
 ```
 
-Alternatively, you can specify `--collapse-empty` to merge empty folders together with the following result:
+Alternatively, you can specify `--collapse-empty` to merge empty folders together, producing the following result:
 
 ```text
 document
@@ -215,7 +257,7 @@ folderA/
 ### Renderer
 
 Use the `ConfluenceRenderer` class to generate Confluence Storage Format
-output from a markdown document.
+output from a Markdown document.
 
 ```python
 import mistune
@@ -236,7 +278,7 @@ API that allows you to create, read, and update pages.
 ```python
 from md2cf.api import MinimalConfluence
 
-confluence = MinimalConfluence(host='http://example.com/rest/api', username='foo', password='bar')
+confluence = MinimalConfluence(host='https://example.com/rest/api', username='foo', password='bar')
 
 confluence.create_page(space='TEST', title='Test page', body='<p>Nothing</p>', update_message='Created page')