diff options
| -rw-r--r-- | .gitignore | 21 | ||||
| -rw-r--r-- | LICENSE | 19 | ||||
| -rw-r--r-- | README.md | 49 | ||||
| -rw-r--r-- | TODO.md | 13 | ||||
| -rw-r--r-- | alternatives.md | 21 |
5 files changed, 123 insertions, 0 deletions
diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..81a4762 --- /dev/null +++ b/.gitignore @@ -0,0 +1,21 @@ +*.o +*.a +*.pyc +#*# +*~ +*.swp +.* +*.tmp +*.old +*.profile +*.bkp +*.bak +[Tt]humbs.db +*.DS_Store +build/ +_build/ +src/build/ +*.log + +# Don't ignore this file itself +!.gitignore @@ -0,0 +1,19 @@ +Copyright (c) 2017 Bryan Newbold + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..7517471 --- /dev/null +++ b/README.md @@ -0,0 +1,49 @@ + +A simple python script for uploading markdown files to Confluence (a +proprietary wiki system). If you find yourself needing to publish documentation +to Confluence at work, but wish that instead you could just write markdown and +keep it versioned in git instead of contending with browser-mangling javascript +and pull-down menus, then this tool is for you! + +This is crude and one-way: there is no mechanism for synchronizing or retaining +edits made by peers, won't look the way you want it to, there are no unittests, +it will mangle your wiki space, and confound your sysadmins. Have Fun! + +# Installation and Setup + +You need **Python 3**, the **requests** python(3) library, and **pandoc** +installed first: + + # debian/ubuntu + sudo apt install python3 python3-requests pandoc + + # homebrew? guessing here + sudo brew install python3 py3-requests pandoc + +To experiment you can checkout this repo and run commands locally. If you like +it you can install system-wide with: + + sudo make install + +On the Confluence side, it uses the newer REST API (not the old XML-RPC API) +and generates complete pages in "Confluence storage" syntax, so if you're lucky +it will Just Work without needing any administrative intervention. + +# Usage + + export CONFLUENCE_USER=`whoami` + export CONFLUENCE_PASSWORD="password123" + export CONFLUENCE_URL="https://evil-corp.jira.com/wiki/" + ./divergence -s "PROD25" Acme_Widget_Docs.md + +This will create a new page "Acme Widget Docs" under the space with ID +"PROD25" (or overwrite it if it already exists). When experimenting you +probably want to use your personal space, which will be something like +"~bitdiddle". If you blow away something accidentally, it should be possible to +revert the push in the wiki interface (this has not been verified). + +Multiple files can be uploaded at the same time. + +If you have in-line images you'll need to upload them manually. Haven't tried +it yet. + @@ -0,0 +1,13 @@ + +- `--help` +- installation procedure +- extract space, title, and/or page ID from pandoc yaml header + +Nice to have, but unlikely to be implemented: + +- optional table of contents +- more than just markdown (restructured text, html, etc) +- configurable banner at the top of rendered pages ("this uploaded from...") +- color output, one line per file +- detecting and uploading included image files as attachments. + `confluence-sync` does this diff --git a/alternatives.md b/alternatives.md new file mode 100644 index 0000000..35c30cf --- /dev/null +++ b/alternatives.md @@ -0,0 +1,21 @@ + +What alternatives are there? +---------------------------- + +[https://github.com/laurencer/confluence-sync]() + +`confluence-sync-tool` was the closest thing to what I wanted. I even tried +hacking in the custom pandoc converter, but ran in to problems with `CNAME` +code blockes getting mangled and gave up trying to debug in Haskell. + +[https://bitbucket.org/atlassianlabs/confluence-pandoc-connect]() + +This is intended to run server-side. It's where I found the +`confluence-storage.lua` pandoc writer. + +[https://github.com/lanyonm/markdown-to-confluence-uploader]() + +Close, but no cigar. Does a meh job converting markdown to wiki markup, then +uses Confluence's API to convert to storage format via the XML-RPC API. The +results are poorly formatted. + |