Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mihaeu/cosmere
Sync your markdown files to Confluence
https://github.com/mihaeu/cosmere
confluence converter doc markdown md
Last synced: about 1 month ago
JSON representation
Sync your markdown files to Confluence
- Host: GitHub
- URL: https://github.com/mihaeu/cosmere
- Owner: mihaeu
- License: mit
- Created: 2019-12-18T18:59:37.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-06-16T10:19:58.000Z (5 months ago)
- Last Synced: 2024-09-30T00:43:35.400Z (about 1 month ago)
- Topics: confluence, converter, doc, markdown, md
- Language: TypeScript
- Homepage: https://mihaeu.github.io/cosmere/
- Size: 656 KB
- Stars: 34
- Watchers: 3
- Forks: 10
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Cosmere
Sync your markdown files to confluence.
## Features
- upload new versions only when necessary
- upload/delete local images as attachments
- supports the original markdown spec and parts from [CommonMark](https://marked.js.org/#specifications) and [GitHub Flavored Markdown](https://marked.js.org/#specifications)
- can be used as a CLI command or in a script
## Usage
### Global Installation
```bash
npm install -g cosmere
# or
yarn global add cosmere
```
### Library
```bash
npm install --save-dev cosmere
# or
yarn add --dev cosmere
```
### Configuration
To get started generate configuration using
```bash
cosmere generate-config [--config=]
```
which produces:
```json
{
"baseUrl": "",
"user": "",
"pass": "",
"personalAccessToken": "",
"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, ...):
```ini
CONFLUENCE_USERNAME=YOUR_USERNAME
CONFLUENCE_PASSWORD=YOUR_PASSWORD
```
or
```ini
CONFLUENCE_PERSONAL_ACCESS_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):
```bash
CONFLUENCE_USER=YOUR_USERNAME CONFLUENCE_PASSWORD=YOUR_PASSWORD cosmere
# or
CONFLUENCE_PERSONAL_ACCESS_TOKEN="" cosmere
```
### Run
```bash
# global installation
cosmere --help
# local installation with yarn
yarn cosmere --help
# local installation with npm
npm run cosmere --help
# or plain
node_modules/.bin/cosmere --help
```
or create an alias:
```json
{
"scripts": {
"pushdoc": "cosmere"
}
}
```
## Using Cosmere as a library
```js
import cosmere from "cosmere/dist/src/lib";
import ConfluenceRenderer from "cosmere/dist/src/ConfluenceRenderer";
class CustomRenderer extends ConfluenceRenderer {
constructor(options, config, page) {
super(options, config, page);
}
image(href, title, text) {
if (href.startsWith("http")) {
return ``;
}
return ``;
}
}
const config = {
baseUrl: "",
user: "",
pass: "",
cachePath: "build",
prefix: "This document is automatically generated. Please don't edit it directly!",
insecure: false,
force: false,
fileRoot: "/usr/bin/myawesomefolder",
pages: [
{
pageId: "1234567890",
file: "README.md", // this path will be evaluated as fileRoot + file
title: "Optional title in the confluence page, remove to use # h1 from markdown file instead",
},
],
customRenderer: CustomRenderer,
};
await cosmere(config);
```
## Troubleshooting
### Custom certificates on Confluence instance
Use the `--insecure` option for your `cosmere` 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
1. Add feature/fix bugs etc.
2. Document changes in [`CHANGELOG.md`](CHANGELOG.md) (with the new [version](https://semver.org/))
3. Commit everything
4. Push/merge to main
5. Run
```bash
yarn release
yarn np
```
## History
### md2confluence
I had various scripts that stitched markdown files together and uploaded them. I forked [`md2confluence`](https://github.com/jormar/md2confluence) by [Jormar Arellano](https://github.com/jormar) 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
The project diverged from its original intent and so I decided to rename it. [Cosmere](https://coppermind.net/wiki/Cosmere) is the wonderful universe of various books written by [Brandon Sanderson](https://www.brandonsanderson.com/). If you are into fantasy I strongly recommend checking him out.
## License
See [LICENSE](LICENSE).