Use directory structure mapped to parent for page structures and front matter for properties

[sheldonhull]

I was looking for a tool that would work on markdown for Confluence and thankfully stumbled upon this. Very nice work and thanks for sharing it!

I had a suggestion to consider based on past work I did with another project similar to this: asciidoc-confluence

Here's a blog post demo for how I used it if you are interested. Asciidoc Distributed Docs as Code

1. Map the job to the parent page id.
   1. All subsequent pages are just mapped from this as subpages automatically, so it uses the directory structure automatically with no need to map in the child spaces etc. If I'm misunderstanding the directions here and this isn't required please correct me. Seemed like this mapping was required on all pages when I skimmed the readme.
2. Use front matter for titles and any other optional property mapping.
   1. If special mapping is required, leverage front matter instead of html tagging. Front matter is a standardized approach for markdown. Why would this help? My example is a doc repo I have. The presentation format has changed over time. I've used mkdocs, native github asciidoc rendering, and later markdown rendered in another source control system. All of these supported front matter. I maintained the front matter tags, name, summary etc regardless of if using them for that rendering precisely so I'd have flexibility in the future to use mkdocs, hugo, or another static site renderer in the future.

Consider for example:

---
title: My Fancy Page
summary: My excerpt
tags:
- foo
- bar

If the configuration for your tooling would allow me to use title: My Fancy Page as the default title value I'd be able to ensure unique naming and titles that matched without any special html tagging.

The biggest benefit I've found to the workflow I describe is with tools like mkdocs, asciidoc-confluence, etc it means the management of the subdirectories and contents is very simple as the directory structure is reproduced as directories and pages automatically. Having to map this myself increases the complexity of managing.

Look forward to any feedback or thoughts on this.

[kovetskiy]

Hey there,

Thank you for the suggestion. We don't use a front matter instead of HTML tagging because services like GitHub can't properly render them. Lots of people use mark to render docs on GitHub wiki and Confluence at the same time.

The directory structure feature sounds interesting, but I would like to note that it doesn't actually solve the same problems that the current implemented approach has:

• renaming documents is not supported (mark just creates a new one)
• deleting documents is not supported

Btw, we also don't want to make it too opinionated because I know a few people who use mark just to edit a single page using flag -l: -l <url> — Edit specified Confluence page. If -l is not specified, file should contain metadata (see above).

[sheldonhull]

That's interesting. I know when I used the asciidoc-confluence project the directory structure works and a rename would delete the existing page and replace with a new one.

In fact, that was one of my favorite parts, as it ensured the child nested structure of pages was preserved and all content purged if I purged from repo.

I'll have to experiment further then with the current approach, so you can close this as irrelevant to the goals of this particular project. Thanks for responding!

[WarFox]

Can we have support for front matter as an opt-in freature? I say this because many existing markdown to html tools support front matter as standard (jekyll, hugo, hexo etc). I have existing documentation with front matter, and I need to publish to both confluence and a static website. It'll be nice if both formats are supported out of the box

[kovetskiy]

I'm not sure how to handle such cases, you probably want this front matter in a specific format toml/yaml and a specific separator which should not be defined by mark itself since lots of people use lots of different tools with different front matter formats.

What I'd do in your case is just store files with front matter and just cut the front matter before sending files to confluence:

---
title: aa
date: blah
---

<!-- Space: XXX ->

Test

 $ sed '/---/,/---/d' document.md > document.mark.md
 $ mark [...] document.mark.md

[WarFox]

Thank you @kovetskiy

While sed will work, I still think it'll create duplicate data issue, e.g. you have have to maintain title data with front matter and <-- Title: xxx -->

I tried adding front matter support with this library https://github.com/adrg/frontmatter. It supports yaml, toml and json frontmatter. I have a draft PR to show to idea here https://github.com/kovetskiy/mark/pull/122

Do you think this is a good direction?

[LeeShan87]

Is there any update on this issue or on the PR @WarFox? Front matter support would be great.

[WarFox]

ah sorry no, I haven't made any progress after that draft PR #122. Do you want to collaborate on it @LeeShan87 ?

[helmut72]

While sed will work, I still think it'll create duplicate data issue, e.g. you have have to maintain title data with front matter and <-- Title: xxx -->

Just extend the example above like this:

# Get title from front matter and use syntax of "Mark" format. Use only first match of "Title" with -m 1 option.
title='<!-- '$(grep -m 1 "Title:" example.md)' -->'

# Delete front matter header only: Use 2nd match of a "---" line plus delete all above, but no further "---" lines in the rest of the document.
sed -i '1,/---/d' example.md

# Insert Title on top
sed -i "1s/^/$title\n/" example.md

I run this in a script started by a hook and also check some other entries, if this document will be uploaded to Confluence or not.

[mrueg]

With https://github.com/kovetskiy/mark/pull/343 you'd be able to define parent pages via the CLI. You can extract the path of the file you want to push via dirname or similar and add it as a command-line argument.

[mrueg]

As #343 got merged, I'll close this issue. Feel free to reopen, if you think this is not providing a good enough solution