marked-space

Marked Space is a tool for generating complete Confluence spaces from Markdown. This tool was written to better support writing and managing multi-page documentation with the following features:

• Internal links are done by filename, so that you can change titles as you see fit. No more broken links (or at least marked-space will warn you first).
• Moving and recoganising documentation is easy. For example, moving pages in the heirarchy doesn't delete the old page and create a new one.
• Similarly, retitling also works. Unfortunately, it's still hard to do both at once - but that may change in the future (I'm already having ideas about fixing it as I write this...)
• Referenced images are automatically added so the page displays correctly.
• Flexible macro support allows you to extend marked-space, for instance with new Confluence macros, or even create and manage your own templates outside of the Confluence system.
• ... and more to come!

Marked Space was heavily inspired by the Mark tool, but adds a more "space wide" view.

Additionally, Marked Space would not be possible without these fantastic libraries:

• comrak
• serde
• reqwest
• clap
• anyhow and thiserror
• assert_fs
• tera

Getting Started

Firstly, you'll need to create a space and take note of the space key marked-space will not create the space for you to avoid accidentally creating masses of spaces for random directories. If you don't know your space, you should see it in the URL for the space homepage, ie if your homepage is https://example.atlassian.net/wiki/spaces/TEAM/pages/107639, then the space key is TEAM.

Then create a space for your markdown using the same key:

mkdir TEAM
cd TEAM
cat > index.md <<EOF
# My First Marked Space

Your content goes here
EOF

Setting up Credentials

Go to your Atlassian profile and generate a new API token at https://id.atlassian.com/manage-profile/security/api-tokens. For covenience we'll use .env files, but you can also set this directly in the environment:

API_USER=<your_atlassian_user_email>
API_TOKEN=<the_api_token_you_generated>
CONFLUENCE_HOST=<the_hostname_of_your_confluence_instance>

Ideally you'll be executing updates from a CI/CD pipeline, which will have its own means of securely storing and setting environment variables.

With credentials setup, you can now either execute marked-space using the docker image, some of the prebuilt binaries or build it for yourself from source.

Using the Docker Image

# assuming the documentation is in the subdirectory "TEAM"
docker run --rm -ti --env-file .env -v $PWD/TEAM:/TEAM jamesallanlloyd/marked-space --space /TEAM

Using Prebuilt Binaries

See https://github.com/james-allan-lloyd/marked-space/releases. Currently build self-contained binaries for:

• Ubuntu 22.04 LTS or compatible
• Windows

Building from Source

It's all so easy with cargo 😁.

cargo install --path .
marked-space --space TEAM

Further Reading

Checkout the user guide in the example space... this also serves as a test marked-space that is all deployable to your test instance (provided you've created the TEAM space).