# confluence.md
Push markdown files straight to a Confluence page.
## What it does?
`confluence.md` allows you to push any markdown file to Confluence. You can create
a new page (under given parent) or update an existing one.
## How to install?
It's as easy as:
```sh
$ pip install confluence.md
# If the above doesn't work, your `pip` command points to different
# python than installation than `python` command. If so, run:
$ python -m pip install confluence.md
```
## How to use it in command-line?
Markdown to Confluence
Example workflow:
#### 1. Create page
Create a new page under `--parent_id`:
```sh
$ confluence.md --user user@name.net \ # Atlassian username
--token 9a8dsadsh \ # API token or --password
--url https://your-domain.atlassian.net \ # Confluence instance URL
create \ # create or update
--file README.md \ # markdown file
--parent_id 182371 \ # parent page
--title "new title" # title for a new page
--add_meta # adds meta to source.md file
```
#### 2. Verify markdown
The page is created and the file is decorated with metadata:
```sh
$ head -n 3 markdown.md
---
confluence-url: https://your-domain.atlassian.net/wiki/spaces/SP/pages/18237182/new+title
---
```
#### 3. Update page
Performing an update does not require providing `--page_id` and `--url`:
```sh
$ confluence.md --user user@name.net --token 9a8dsadsh update --file README.md
```
Doing an update with `--page_id` and `--url` is still possible.
Consider adding useful `--add_info` option.
To create Atlassian API Token go to [api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
## Command line arguments
**Actions:**
- `update` Updates page content based on given `page_id` or metadata in Markdown file
- `create` Creates new page under given `parent_id`
**positional arguments:**
- `{update,create}` Action to run
**optional arguments:**
- `-h`, `--help` show this help message and exit
- `--file FILE` input markdown file to process
- `--add_meta` adds metadata to .md file for easy editing
- `--add_info` adds info panel **automatic content** do not edit on top of the page
- `--add_label` `ADD_LABEL` adds label to page
- `--convert_jira` convert all Jira links to issue snippets (either short [KEY-ID] format or full URL)
**note**: this options works only in Cloud instances with [Secure Markdown](https://marketplace.atlassian.com/plugins/secure-markdown-for-confluence) installed
- `-v`, `--verbose` verbose mode
- `-q`, `--quiet` quiet mode
**required auth parameters:**
- `-u` `USER`, `--user` `USER` Atlassian username/email
- `-t` `TOKEN`, `--token` `TOKEN` Atlassian API token
- `-p` `PWD`, `--password` `PWD` Atlassian password (used in on-prem instances)
- `-l` `URL`, `--url` `URL` Atlassian instance URL
- `-n`, `--no_verify_ssl` don't verify SSL cert (useful in on-prem instances)
**create page parameters:**
- `--parent_id` `PARENT_ID` define parent page id while creating a new page
- `--title` `TITLE` define page title while creating a new page
- `--overwrite` force overwrite if page with this title already exists
**update page arguments:**
- `--page_id` `PAGE_ID` define (or override) page id while updating a page
## How to use it in a Python script?
ConfluenceMD wasn't designed to be used this way, but it's fairly simple to embed
it in a Python script. See this example:
```python
from md2cf.utils.confluencemd import ConfluenceMD
conf_md = ConfluenceMD(username=user,
md_file=md_file,
token=token,
url=url,
convert_jira=convert_jira)
# create new page under parent_id
new_page_id = conf_md.create_new("parent_id", "title")
# update existing page with given page_id
page_id = conf_md.update_existing("page_id")
```
Raw data
{
"_id": null,
"home_page": "https://github.com/szn/confluence.md",
"name": "confluence.md",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "markdown, confluence, md, atlassian",
"author": "Szymon Nieradka",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/2e/17/937eccae14cfd3cff56dd0cd76b390c2b7c94d489559e4f145ad46befe49/confluence_md-0.4.7.tar.gz",
"platform": null,
"description": "# confluence.md\n\nPush markdown files straight to a Confluence page.\n\n## What it does?\n\n`confluence.md` allows you to push any markdown file to Confluence. You can create\na new page (under given parent) or update an existing one.\n\n## How to install?\n\nIt's as easy as:\n\n```sh\n$ pip install confluence.md\n\n# If the above doesn't work, your `pip` command points to different\n# python than installation than `python` command. If so, run:\n$ python -m pip install confluence.md\n```\n\n## How to use it in command-line?\n\nMarkdown to Confluence\n\nExample workflow:\n\n#### 1. Create page\n\nCreate a new page under `--parent_id`:\n```sh\n$ confluence.md --user user@name.net \\ # Atlassian username\n --token 9a8dsadsh \\ # API token or --password\n --url https://your-domain.atlassian.net \\ # Confluence instance URL\n create \\ # create or update\n --file README.md \\ # markdown file\n --parent_id 182371 \\ # parent page\n --title \"new title\" # title for a new page\n --add_meta # adds meta to source.md file\n```\n\n#### 2. Verify markdown\n\nThe page is created and the file is decorated with metadata:\n\n```sh\n$ head -n 3 markdown.md\n---\nconfluence-url: https://your-domain.atlassian.net/wiki/spaces/SP/pages/18237182/new+title\n---\n```\n\n#### 3. Update page\n\nPerforming an update does not require providing `--page_id` and `--url`:\n\n```sh\n$ confluence.md --user user@name.net --token 9a8dsadsh update --file README.md\n```\n\nDoing an update with `--page_id` and `--url` is still possible.\n\nConsider adding useful `--add_info` option.\n\nTo create Atlassian API Token go to [api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).\n\n## Command line arguments\n\n**Actions:**\n\n- `update` \t\tUpdates page content based on given `page_id` or metadata in Markdown file\n- `create` \t\tCreates new page under given `parent_id`\n\n**positional arguments:**\n\n- `{update,create}` Action to run\n\n**optional arguments:**\n\n- `-h`, `--help` show this help message and exit\n- `--file FILE` input markdown file to process\n- `--add_meta` adds metadata to .md file for easy editing\n- `--add_info` adds info panel **automatic content** do not edit on top of the page\n- `--add_label` `ADD_LABEL` adds label to page\n- `--convert_jira` convert all Jira links to issue snippets (either short [KEY-ID] format or full URL)\n **note**: this options works only in Cloud instances with [Secure Markdown](https://marketplace.atlassian.com/plugins/secure-markdown-for-confluence) installed\n- `-v`, `--verbose` verbose mode\n- `-q`, `--quiet` quiet mode\n\n**required auth parameters:**\n\n- `-u` `USER`, `--user` `USER` Atlassian username/email\n- `-t` `TOKEN`, `--token` `TOKEN` Atlassian API token\n- `-p` `PWD`, `--password` `PWD` Atlassian password (used in on-prem instances)\n- `-l` `URL`, `--url` `URL` Atlassian instance URL\n- `-n`, `--no_verify_ssl` don't verify SSL cert (useful in on-prem instances)\n\n**create page parameters:**\n\n- `--parent_id` `PARENT_ID` define parent page id while creating a new page\n- `--title` `TITLE` define page title while creating a new page\n- `--overwrite` force overwrite if page with this title already exists\n\n**update page arguments:**\n\n- `--page_id` `PAGE_ID` define (or override) page id while updating a page\n\n## How to use it in a Python script?\n\nConfluenceMD wasn't designed to be used this way, but it's fairly simple to embed\nit in a Python script. See this example:\n\n```python\nfrom md2cf.utils.confluencemd import ConfluenceMD\n\nconf_md = ConfluenceMD(username=user,\n md_file=md_file,\n token=token,\n url=url,\n convert_jira=convert_jira)\n\n# create new page under parent_id\nnew_page_id = conf_md.create_new(\"parent_id\", \"title\")\n\n# update existing page with given page_id\npage_id = conf_md.update_existing(\"page_id\")\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Markdown to Confluence - upload any .md files to your Confluence cloud page",
"version": "0.4.7",
"project_urls": {
"Bug Tracker": "https://github.com/szn/confluence.md/issues",
"Homepage": "https://github.com/szn/confluence.md"
},
"split_keywords": [
"markdown",
" confluence",
" md",
" atlassian"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7ed902c47f31257930f2b201c51c184818a704d52ea88770c185abd01ed5a7c4",
"md5": "bac21260f857929c8827850778b900ff",
"sha256": "9c8a7a2978b38ed8fc807224d109106e9b8acd8ea149139ced1356b45fc1dad9"
},
"downloads": -1,
"filename": "confluence.md-0.4.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bac21260f857929c8827850778b900ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 11636,
"upload_time": "2024-09-12T16:18:25",
"upload_time_iso_8601": "2024-09-12T16:18:25.658751Z",
"url": "https://files.pythonhosted.org/packages/7e/d9/02c47f31257930f2b201c51c184818a704d52ea88770c185abd01ed5a7c4/confluence.md-0.4.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2e17937eccae14cfd3cff56dd0cd76b390c2b7c94d489559e4f145ad46befe49",
"md5": "4106932c604468b9d74012e6564ecf0f",
"sha256": "c3e516f8c85f52e10bf1e45bb7a77b824f91c1403ea4edfbd040c6af92c58444"
},
"downloads": -1,
"filename": "confluence_md-0.4.7.tar.gz",
"has_sig": false,
"md5_digest": "4106932c604468b9d74012e6564ecf0f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 9715,
"upload_time": "2024-09-12T16:18:27",
"upload_time_iso_8601": "2024-09-12T16:18:27.535492Z",
"url": "https://files.pythonhosted.org/packages/2e/17/937eccae14cfd3cff56dd0cd76b390c2b7c94d489559e4f145ad46befe49/confluence_md-0.4.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-12 16:18:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "szn",
"github_project": "confluence.md",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "atlassian-python-api",
"specs": [
[
">=",
"3.41.14"
]
]
},
{
"name": "coloredlogs",
"specs": [
[
">=",
"15.0.1"
]
]
},
{
"name": "markdown2",
"specs": [
[
">=",
"2.4.10"
]
]
},
{
"name": "termcolor",
"specs": [
[
">=",
"2.3.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"8.3.1"
]
]
}
],
"lcname": "confluence.md"
}
JSON
