{"id":19320489,"url":"https://github.com/aluriak/vimoku","last_synced_at":"2026-01-28T21:31:01.060Z","repository":{"id":62587478,"uuid":"268386858","full_name":"Aluriak/vimoku","owner":"Aluriak","description":"edit dokuwiki pages with your favorite editor  (i.e. $EDITOR)","archived":false,"fork":false,"pushed_at":"2023-08-14T20:31:00.000Z","size":132,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-17T04:49:55.255Z","etag":null,"topics":["dokuwiki","dokuwiki-api","rtc","texteditor","xml-rpc"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Aluriak.png","metadata":{"files":{"readme":"README.mkd","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-01T00:13:08.000Z","updated_at":"2023-08-14T20:31:04.000Z","dependencies_parsed_at":"2024-11-10T01:29:19.622Z","dependency_job_id":"eb69f2d7-cf40-45a5-adce-70dc5886fabb","html_url":"https://github.com/Aluriak/vimoku","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aluriak%2Fvimoku","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aluriak%2Fvimoku/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aluriak%2Fvimoku/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aluriak%2Fvimoku/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Aluriak","download_url":"https://codeload.github.com/Aluriak/vimoku/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250237798,"owners_count":21397399,"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","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":["dokuwiki","dokuwiki-api","rtc","texteditor","xml-rpc"],"created_at":"2024-11-10T01:29:14.705Z","updated_at":"2026-01-28T21:31:01.010Z","avatar_url":"https://github.com/Aluriak.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vimoku\n\nEdit pages of a dokuwiki instance with your favorite editor.\n\nUse the [RPC-XML interface](https://www.dokuwiki.org/devel:xmlrpc) of dokuwiki, accessed using [dokuwikixmlrpc](https://github.com/kynan/dokuwikixmlrpc).\n\nTested with python 3.8. Should work with 3.6. Will not with 3.5 (sorry, f-strings are the best).\n\n\n\n# Installation\n## setup (manual)\nInstall vimoku.py somewhere, make it executable. You probably want to rename it just `vimoku`, or create aliases in your dot files.\n\nCreate a new repository with `git init`, and, in the `git/config` file, add the following section:\nYou need to create the file `$XDG_CONFIG_HOME/vimoku/vimoku.ini` (Your `$XDG_CONFIG_HOME` is probably equal to `~/.config`) as follow:\n\n    [wiki:default]\n    url = https://yourwiki.url.net\n    user = john\n    password = yourpassword\n\nThe url is the url of your wiki. User and password are the login for the account you will use to publish your editions on the wiki.\nIt therefore must be an existing dokuwiki user allowed to [use RTC calls](https://www.dokuwiki.org/devel:xmlrpc#get_it_working).\n\nOther options are available, notably `editor` to set the editor to choose its options. See [editor options section](#editor-options) for an example. This readme explains more options and features.\n\n\n## setup (semi-manual)\n\n    pip install vimoku  # don't forget to verify version of pip, python, OS, timeline, blahblah\n\nPython dependencies are automatically installed, but you still need to install a `vimoku.ini` in your config directory. Only now, you have vimoku ready to fire with `python -m vimoku`.\n\n\n## dependencies\nOnly one, really : [dokuwikixmlrpc](https://github.com/kynan/dokuwikixmlrpc).\nIf you are to browse it, there is no documentation, but [the code](https://github.com/kynan/dokuwikixmlrpc/blob/master/dokuwikixmlrpc.py)\nis short and understandable. You probably look for the [DokuWikiClient object](https://github.com/kynan/dokuwikixmlrpc/blob/master/dokuwikixmlrpc.py#L128).\n\n`pip install dokuwikixmlrpc` should be enough, probably with `--user`.\nYou could also copy paste in place of the imports the [single source file of dokuwikixmlrpc](https://github.com/kynan/dokuwikixmlrpc/blob/master/dokuwikixmlrpc.py) in vimoku.py. Don't forget to remove the (call to) main function.\n\n\n\n\n# Usage\n\n## Edition\nUse `vimoku --help` for help.\n\nBasic usage:\n\n    vimoku pageid\n\nYou can edit multiple pages, using standard dokuwiki naming conventions for categories:\n\n    vimoku categ1:page1 page2 categ2:categ3:page3\n\nAnd you may set a commit message (by default, it's `undocumented remote modification`):\n\n    vimoku page2 -m \"guess from where i edit that page ??\"\n\nYour editor will fire a first time, letting you modify the pages you requested. It will fire a second time to let you modify, for each page, the commit message.\nAnd, if you opened other files, it will be fired a third time to ask you if they are wiki pages to retrieve and edit (see *cycling*).\n\n\n## Move and copy\nUsing flags `--move-to` and `--copy-to`, you can modify your wiki structure easily !\nThe only difference between the two is that moving deletes the page after copy.\nNote the existence of specific flags, such as `--redirect` and `--fix-backlinks`. See the below examples.\n\nChange the name of a page, if the new name is not an existing page:\n\n    vimoku categ:pageid --move-to othercateg:newpageid\n\nChange the name of a page, if the new name is not an existing page, with a redirection in the old page to the new one:\n\n    vimoku categ:pageid --move-to othercateg:newpageid --redirect\n\nCopy the category `bar` into another (note the `:` that indicate that the *category*, not the page, is to be considered):\n\n    vimoku bar: --copy-to baz\n\nMove all content of a category `bar` into `baz`, and put a redirection message in the moved pages:\n\n    vimoku bar:* --move-to baz --redirect\n\nRename a page, and fix all links that were linking to it before the renaming:\n\n    vimoku page --move-to movedpage --fix-backlinks\n\nVimoku will try to detect any possible fault with what you provided,\nthen will ask you to review the move with your editor. There, you can go wild and erase entire pages by not paying attention to what you do.\n\n\n### Categories selection\nThe next example shows some advanced details regarding categories.\nLet's consider the wiki containing the following pages:\n\n    a\n    b\n    b:d:e\n    b:f\n    c\n    c:g\n\nThe following command:\n\n    vimoku a b: c --move-to h --redirect\n\nShould move the pages to obtain:\n\n    b\n    c:g\n    h:a\n    h:b:d:e\n    h:b:f\n    h:c\n\nIf you also wanted to move `b` and `c:g`, you should indicate that you want to move `b` and `c:`, thus:\n\n    vimoku a b b: c c: --move-to h --redirect\n\n\n## Edit on different dokuwiki instances\nVimoku supports the existence of many wikis in the configuration file. This is achieved by populating your `vimoku.ini` with different wikis.\nThis also allows you to handle multiple identities on a single wiki.\nThe following ini file provides an example of three different accounts on two different wikis, setting one of them as the default:\n\n    [wiki:default]\n    url = https://wiki.one.example.net\n    user = john\n    password = passwordone\n    [wiki:second]\n    url = https://wiki.two.example.net\n    user = john\n    password = passwordtwo\n    [wiki:alt]\n    url = https://wiki.one.example.net\n    user = mysteriousguy\n    password = mysteriouspassword\n\nNow, you can specify explicitely which wiki to consider when using the CLI. For instance, you could edit a page using your alternative identity on the first wiki:\n\n    vimoku categ:page alt:::page second/page\n\nThis will enable you to edit `categ:page` on the `default` wiki, `page` with your alternative identity on the same wiki, and `page` on the `second` wiki.\nSlash or triple colons means the same thing.\n\nYou can also copy from one instance to another, here copying all meeting reports from wiki one to wiki two:\n\n    vimoku one/meeting:* --copy-to two/meeting:\n\nMore details:\n- slashes are accepted in input as wiki separator, but internally the token triple colon `:::` is used.\n- before the slash/triple colon is the wiki name, as defined in the configuration file. After the slash/triple colon is the page name in the remote wiki.\n- when no wiki name is given, `default` is used. You can [change this](#set-a-different-default-wiki).\n\n\n\n# tips\n\n\n## cycling\nOnce in your editor, if you create more files in the temporary directory containing the files you asked for edition, they will not be removed.\nInstead, you will be prompted (using your $EDITOR) about which files you want to edit properly.\n\nThe whole program will run again, this time retrieving the new files you asked for.\n\nNB: if you wrote things in those manually opened files, you will loose your data. Even if the page doesn't exists on the wiki. Yes, that sucks. Help me.\n\n\n## editor options\nYour `vimoku.ini` accept the option `editor`, to explicitely set the editor command if you don't trust your `$EDITOR` environment variable or wants to provide options to your editor.\n\nIt is formated with the variables `{cwd}`, the path to the directory holding the files you will be editing, and `{pages}`, that list the pages to be edited. If `{pages}` is not given, files to open are fed at the end of the command.\n\nFor instance, using vim, i ended up with the following value:\n\n    [options]\n    editor=/usr/bin/vim -c \":cd {cwd}\" -p\n\nThis ensures that vim opens each file in its own tab (`-p`), and uses the temporary directory containing all files as working dir so opening more files is easy (`-c \":cd {cwd}\"`, where `{cwd}` will be substituted by the path to current working directory).\n\nNote that since pages are added by default after the command, i didn't have to explicitely add `{pages}` after the `-p` option. I could have. I didn't.\n\n\n## Set a different default wiki\nWhen setting multiple wikis in your ini file, you may use the option `default_wiki` to provide which wiki to use when no name is given. Example:\n\n    [options]\n    default_wiki = second\n    [wiki:first]\n    url = https://wiki.one.example.net\n    user = john\n    password = passwordone\n    [wiki:second]\n    url = https://wiki.two.example.net\n    user = john\n    password = passwordtwo\n\n\n## Aliases\nAny good system offers user-defined aliases, but keep in mind the converse error.\n\nYour aliases are set, under the `[option]` header (support for per-wiki aliases would be awesome, wouldn't it ?),\nas in the following example:\n\n    [options]\n    aliases = pp: c1:c2, aaaaaaa: a:a:a\n\nThis allows you to open page `c1:c2` with `vimoku pp`, page `c1:c2:p` with `vimoku pp:p`, or page `a:a:a:stayingalive` with `aaaaaaa:stayingalive`.\nNote that this last alias is not really helpful. Choose better aliases, kids.\n\nAliases substitution only occur at the *beginning* of the pagename. Hence, `vimoku a:pp:a` will happily open `a:pp:a`, not `a:c1:c2:a`.\n\nThis is an arbitrary choice that, to me, seems to limit the number of unexpected behaviors when you are editing pages with long and weird names. Maybe that risk is worth the gain ?\nThis i do not know. Tell me if you know something about that.\n\n\n# Work to be done\n\n- fix the data loss problem when writing a new file and asking the program to upload it.\n- what about using a watchdog to automatically download and lock the newly opened file ? Or provide a vim plugin ?\n- use the CLI's `--minor` flag\n- use `tmpfile` instead of flooding `.config/vimoku`\n- is it possible to upload a media ? yes, it is. see `client.put_file`\n- there is few TODOs in the code.\n- aliases in config file, where writing `aliases = pp: c1:c2` makes command `vimoku pp:a` edit page `c1:c2:a`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faluriak%2Fvimoku","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faluriak%2Fvimoku","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faluriak%2Fvimoku/lists"}