{"id":28370921,"url":"https://github.com/garyns/confluence-config-documentator","last_synced_at":"2025-08-11T18:16:52.057Z","repository":{"id":57205556,"uuid":"42961321","full_name":"garyns/confluence-config-documentator","owner":"garyns","description":"Create or update pages in Confluence to document configuration files","archived":false,"fork":false,"pushed_at":"2016-06-22T02:20:43.000Z","size":535,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-09T03:35:15.637Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/garyns.png","metadata":{"files":{"readme":"README.MD","changelog":"CHANGELOG.MD","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-09-22T21:16:41.000Z","updated_at":"2016-02-18T10:42:24.000Z","dependencies_parsed_at":"2022-09-12T22:50:16.904Z","dependency_job_id":null,"html_url":"https://github.com/garyns/confluence-config-documentator","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/garyns/confluence-config-documentator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garyns%2Fconfluence-config-documentator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garyns%2Fconfluence-config-documentator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garyns%2Fconfluence-config-documentator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garyns%2Fconfluence-config-documentator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/garyns","download_url":"https://codeload.github.com/garyns/confluence-config-documentator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/garyns%2Fconfluence-config-documentator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269688126,"owners_count":24459406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-29T07:12:08.063Z","updated_at":"2025-08-11T18:16:52.021Z","avatar_url":"https://github.com/garyns.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Confluence Config Documentator (confdoc \u0026 confwatch)\n\n\u003eA command line utility to document textual configurations files in Atlassian Confluence.\n\nThe name is a mouth full, but the concept behind confdoc is simple - to create and update Confluence pages with the content of a configuration text file (or any text file for that matter).\n\n[![NPM](https://nodei.co/npm/confluence-config-documentator.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/confluence-config-documentator/)\n\n## Installation\n\n```\n  npm install -g confluence-config-documentator\n```\nNow you can type `confdoc` and `confwatch` on the command line.\n\n## GIT Cloning\n\nIf you are cloning / forking from GIT, run `npm install` to install dependencies.\n\n```\ngit clone https://github.com/garyns/confluence-config-documentator\ncd confluence-config-documentator\nnpm install\n```\n\n\n## Confdoc Usage\n\n`confdoc` is an commline tool to upload a file to Confluence.\n\n```\nconfdoc --server \u003cconfluence_server_url\u003e --username \u003cusername\u003e --password \u003cpassword\u003e [--config \u003cfile\u003e] [--spaceKey \u003ckey\u003e] [--parentId \u003cid\u003e] [--pageId \u003cid\u003e] [--title \u003ctitle\u003e] [--query \u003cstring\u003e] [--labels \u003clabels\u003e] [--macro \u003cmacro\u003e] [--quiet] [--noupgrade] \u003cinput_file\u003e\n```\n```\nThe following options are supported:\n  -e, --quiet           \tSuspress non-error output\n  -v, --verbose         \tVerbose output and full error messages\n  -n, --noupgrade       \tSuspress new version check\n  -c, --config \u003cARG1\u003e   \tConfiguration File (defaults to ~/.confdoc)\n  -s, --server \u003cARG1\u003e   \tConfluence Server URL\n  -u, --username \u003cARG1\u003e \tConfluence Username\n  -p, --password \u003cARG1\u003e \tConfluence Password\n  -f, --force           \tForce page update even if no change in content\n  -k, --spaceKey \u003cARG1\u003e \tConfluence Space Key\n  -o, --parentId \u003cARG1\u003e \tConfluence Parent Page Id (when creating new page. Space root used if not specified)\n  -i, --pageId \u003cARG1\u003e   \tConfluence Page Id (if not specified, title will be used to find page.)\n  -t, --title \u003cARG1\u003e    \tConfluence Page Title (defaults to hostname:filename)\n  -q, --query \u003cARG1\u003e    \tQuery used to find Confluence Page. Default to title\n  -m, --macro \u003cARG1\u003e    \tMacro type that file content is wrapped in (html, panel, code) (\"code\" by default)\n  -l, --labels \u003cARG1\u003e   \tAdd page labels. Comma separated. (multiple)\n```\nA little later we'll go over some examples.\n\n## Confwatch Usage\n\n`confwatch` will monitor files for changes and upload them to Confluence. Internally confwatch uses confdoc.\n\n```\nconfwatch [--verbose] [--add \u003cfile\u003e] [--remove \u003cfile\u003e] [--list] [--watch]\n```\n\n```\nThe following options are supported:\n  -v, --verbose       \tVerbose output\n  -c, --config \u003cARG1\u003e \tConfiguration File (defaults to ~/.confdoc)\n  -w, --watch         \tWatch files\n  -a, --add \u003cARG1\u003e    \tAdd file (multiple)\n  -r, --remove \u003cARG1\u003e \tRemove file (multiple)\n  -l, --list          \tList watched files\n  -f, --force         \tForce upload of all files now\n```\n\n### Setup\nUnlike `confdoc`, `confwatch` **requires** a configuration file. This can be specified via the `--config` parameter otherwise the the default file `~/.confdoc` is used if it exists. Details of the configuration file are discussed later.\n\n### Watching Files\n**Before using `confwatch`, make sure you can successfully upload files using `confdoc`.**\n\nLets say you want to monitor these files for changes:\n* /etc/my.cnf\n* /etc/httpd/conf/httpd.conf\n\n```\nconfwatch --add /etc/my.cnf --add /etc/httpd/conf/httpd.conf\n```\nThis just adds them to the list of files that `confwatch` will monitor. To actually monitor the files:\n```\nconfwatch --watch\n```\nOr prehaps add something similar to this to /etc/rc.local (or equivalent)\n```\nconfwatch --watch \u003e /var/log/confwatch.log \u0026\n```\nNow whenever one of the watched files changes it will be uploaded to Confluence.\n`confwatch` will update the configuration file with the watched files.\n\n## In-file Usage\n\nYou can add tags to files to override the above arguments. This helps make uploading files easier. We'll cover tags in more detail in the examples section.\n\nSupported tags are\n```\n##Title: \u003cstring\u003e\n##Query: \u003cstring\u003e\n##SpaceKey: \u003cstring\u003e\n##Macro: \u003cstring\u003e\n##PageId: \u003cint\u003e\n##ParentId: \u003cint\u003e\n##Labels: \u003cstring, string, ...\u003e\n```\n\n## The Tag Prefix (##)\n\nThe above examples prefix tags with ##. The tag prefix is actually any two identical characters. So you just use whatever the file's comment syntax is twice, with an optional space. For instance:\n\nAn SQL File\n```\n-- Title: My SQL File\n-- ParentId: 323423\n...\n```\n\nOr an INI file:\n```\n;;Title: My INI File\n;;ParentId: 241234\n...\n```\n\n## Configuration Files\n\nThe configuration file is optional for `confdoc` because all parameters can be specified on the command line. For `confwatch` a configuration file is required.\n\nYou can specify a configuration file with the `--config` parameter. \n\nIf `--config` is not specified and the file `~/.confdoc` exists, it is used (**This feature is only supported in NodeJS 4.1.0+**). \n\nThe configuration file must be valid JSON. \n\nThe following properties are supported:\n\n```\n{\n  \"server\": \"http://myconfluenceserver.com\",\n  \"spaceKey\": \"mySpaceKey\",\n  \"parentId\": \"12345\",\n  \"username\": \"myusername\",\n  \"password\": \"myPassword\",\n  \"timeout\": 60,\n  \"watch\": []\n}\n```\n\n*timeout* is used by `confwatch` only. After a watched file is changed, this is the time in seconds before the file is uploaded to Confluence. Any change to the file within this time will reset the timer. This means you can perform an edit-save-test-edit-save-test cycle without incurring multiple uploads to Confluence.\n\nRemember that *parentId* is only relevant when a new Confluence Page is created.\n\n*watch* is an array of absolute files monitored by `confwatch`. `confwatch --add` and `confwatch --remove` update this array.\n\n## Confdoc Examples\n\nThe examples assume we are executing the commands on a host called myhost.com.\n\n**Example 1**\n\nThe following command will create (or update) a page called myhost.com/etc/httpd/conf/httpd.conf in the root of the Confluence Space with key CONF.\n```\nconfdoc --server http://myconfluenceserver.com --username myusername --password mypassword --spaceKey CONF /etc/httpd/conf/httpd.conf\n```\n\n**Example 2**\n\nThe next example will update the page with id 12333 in space CONF. This page must exist.\n```\nconfdoc --server http://myconfluenceserver.com --username myusername --password mypassword --spaceKey CONF --pageId 12333 /etc/httpd/conf/httpd.conf\n```\n\n**Example 3**\n\nThis example will create or update a page in space CONF, under the page with id 12344. The page title will be set to \"My Apache Config\", and will be labeled with apache and myhost.\n```\nconfdoc --server http://myconfluenceserver.com --username myusername --password mypassword --spaceKey CONF --title \"My Apache Config\" --parentId 12344 --labels \"apache, myhost\" /etc/httpd/conf/httpd.conf\n```\nHere is the same example using comment tags in the head of /etc/httpd/conf/httpd.conf\n```\n##Title: My Apache Config\n##SpaceKey: CONF\n##ParentId: 12344\n##Labels: apache, myhost\n...\n...\n... rest of apache config file  ...\n...\n...\n\n```\nThen:\n```\nconfdoc --server http://myconfluenceserver.com --username myusername --password mypassword /etc/httpd/conf/httpd.conf\n```\n\n## Files are wrapped in Confluence Marcos\nThe content file (that is the file passed into confdoc) is added to a Confluence Page using a {code}, {panel} or {html} macro as defined by the `--macro` parameter. If not specified, a {code} macro is used by default. The title of the macro is the content file plus a time stamp and the md5 hash of the content, Eg \"/etc/httpd/conf/httpd.conf (2015-09-23, 6:45:42am) {4ae537c279fee9d1ec8c2d6fd67e09ac}\". For html macros, a comment is added to the top the macro with the title in it (because the macro does not support a title).\n\nWhen updating a page, confdoc looks for a {code}, {html} or {panel} macro with a title matching the file name of the content file. If a matching macro is found, it is updated. Otherwise a new  macro is appended to the page. This means you can add your own content to the Confluence Page and it will be preserved.\n\n![Conf1](https://raw.githubusercontent.com/garyns/confluence-config-documentator/master/doc/conf1.jpg)\n\n**{html} macro note** To use html macros, you need to enable them in Confluence because they are disabled by default. [See here for instructions on enabling the HTML Macro](https://confluence.atlassian.com/doc/html-macro-38273085.html).\n\n\n## Free Versioning \u0026 Differentials!\n\nWell, it comes with Confluence. When you upload and update your config files in Confluence you can take advantage of Confluence's Page revisions to track changes to your configuration files over time.\n\n## FAQs\n\n**Will confdoc modify my files?**\n\nNo. confdoc never modifies the input file.\n\n**How do I use confdoc to add tags (eg ##Title) to my input files?**\n\nYou need to edit your files manually and add the tags yourself. confdoc never modifies your files.\n\n**I'm getting an error \"Not Found\"**\n\nCheck your Confluence Server URL. Use the `--verbose` option to get a more detailed error message. It will likely mention a 404 status.\n\n**I'm getting an error. What can I do?**\n\nUse the `--verbose` option. This can help output more verbose error messages.\n\n\n**How do I find a Page's Id for use with --parentId or --pageId?**\n\nEdit the page in Confluence. The Page Id is in the address bar.\n![Conf2](https://raw.githubusercontent.com/garyns/confluence-config-documentator/master/doc/conf2.jpg)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaryns%2Fconfluence-config-documentator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgaryns%2Fconfluence-config-documentator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaryns%2Fconfluence-config-documentator/lists"}