MdSync
Bitbucket Repository - Bitbucket
Table of content
[TOC]
Sync your markdown files to wiki's.
Features
- upload new versions only when necessary
- upload/delete local images as attachments
- supports the original markdown spec and parts from CommonMark and GitHub Flavored Markdown
Usage
Global Installation
npm install -g @edisendevops/mdsync
# or
yarn global add @edisendevops/mdsync
Library
npm install --save-dev @edisendevops/mdsync
# or
yarn add --dev @edisendevops/mdsync
Configuration
To get started generate configuration using
mdsync generate-config [--config=<path>]
which produces:
{
"baseUrl": "<your base url including /rest/api>",
"user": "<your username>",
"pass": "<your password>",
"personalAccessToken": "<your personal access token (can be set instead of username/password)>",
"cachePath": "build",
"prefix": "This document is automatically generated. Please don't edit it directly!",
"pages": [
{
"pageId": "1234567890",
"file": "README.md",
"title": "Optional title in the confluence page, remove to use # h1 from markdown file instead"
}
]
}
Continuous Integration
In most scenarios it is not recommended storing your credentials in the configuration file, because you will probably add it to your VCS. Instead, it is recommended to provide the following environment variables in your build pipeline (GitLab CI, GitHub Actions, Jenkins, ...):
CONFLUENCE_USERNAME=YOUR_USERNAME
CONFLUENCE_PASSWORD=YOUR_PASSWORD
or
CONFLUENCE_PERSONAL_ACCESS_TOKEN="<your auth token>"
or add it in front of the command when executing locally (add a space in front of the command when using bash in order to not write the credentials to the bash history):
CONFLUENCE_USERNAME=YOUR_USERNAME CONFLUENCE_PASSWORD=YOUR_PASSWORD mdsync
# or
CONFLUENCE_PERSONAL_ACCESS_TOKEN="<your personal access token>" mdsync
# but it seems that tokens aren't working at the moment
Run
# global installation
mdsync --help
# local installation with yarn
yarn mdsync --hhelp
# local installation with npm
npm run mdsync --help
# or plain
node_modules/.bin/mdsync --help
or create an alias:
{
"scripts": {
"pushdoc": "mdsync"
}
}
Troubleshooting
Custom certificates on Confluence instance
Use the --insecure
option for your mdsync
call in order to not reject invalid certificates. This is risky, and it's preferable to get proper certificates.
Need new features?
Please, feel free to create any issues and pull request that you need.
Release
- Add feature/fix bugs etc.
- Document changes in
CHANGELOG.md
(with the new version) - Commit everything
- Push/merge to main
- Run
npm version <major|minor|patch> --tag-version-prefix=v
git push origin --tags
History
md2confluence
I had various scripts that stitched markdown files together and uploaded them. I forked md2confluence
by Jormar Arellano and started playing around with that, but quickly noticed that many markdown files broke due to the conversion process (wiki -> storage instead of directly to storage).
cosmere
I looked at this package Cosmere and really liked it. Unfortunatelly the pull request https://github.com/mihaeu/cosmere/pull/22 is still open and there is no particular date that it will be implemented. Also, I was run out of time, and couldn't write tests, so I decided to fork it.
MdSync Purposes
The main goal for this project is creating the one way to synchronize markdown README's to the Wiki's (Atlassian Confluence, Notion etc.)
License
See LICENSE.