Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/m-pilia/vim-mediawiki
Vim plugin to edit MediaWiki pages
https://github.com/m-pilia/vim-mediawiki
coc completion mediawiki mediawiki-client neovim nvim-cmp source vim
Last synced: 3 months ago
JSON representation
Vim plugin to edit MediaWiki pages
- Host: GitHub
- URL: https://github.com/m-pilia/vim-mediawiki
- Owner: m-pilia
- License: mit
- Created: 2019-10-23T13:19:56.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-10-26T20:07:27.000Z (3 months ago)
- Last Synced: 2024-10-26T21:54:45.515Z (3 months ago)
- Topics: coc, completion, mediawiki, mediawiki-client, neovim, nvim-cmp, source, vim
- Language: Vim Script
- Homepage:
- Size: 99.6 KB
- Stars: 18
- Watchers: 4
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
vim-mediawiki: vim plugin to edit MediaWiki pages
===============================================================
[](https://travis-ci.org/m-pilia/vim-mediawiki)
[](https://codecov.io/gh/m-pilia/vim-mediawiki/branch/master)
[](https://github.com/m-pilia/vim-mediawiki/blob/master/LICENSE)
This is a plugin to help editing pages of a MediaWiki site from vim/neovim. It
provides:
* filetype detection
* improved syntax highlighting
* page preview
* semantic auto-completion of links and templates with
[coc.nvim](https://github.com/neoclide/coc.nvim) and [nvim-cmp](https://github.com/hrsh7th/nvim-cmp) sources
* [UltiSnips](https://github.com/SirVer/ultisnips) snippets
* `` mappings for text objects
* matching pairs for [matchit.vim](https://github.com/vim/vim/blob/master/runtime/pack/dist/opt/matchit/doc/matchit.txt)
* integration with [vim-surround](https://github.com/tpope/vim-surround)
Installation
============
The plugin can be installed with any package manager. Prerequisites are vim
8.1+ or neovim 0.4+, a working Python3 installation, and the `mwclient` Python
package (`pip install mwclient`).
Auto-completion
===============
If [coc.nvim](https://github.com/neoclide/coc.nvim) is installed and configured
properly, the completion source should work out-of-the-box for buffers of type
`mediawiki`.
For [nvim-cmp](https://github.com/hrsh7th/nvim-cmp), add the `cmp_mediawiki`
source:
```lua
require('vim-mediawiki.cmp_mediawiki')
require('cmp').setup({
sources = {
{name = 'cmp_mediawiki'},
},
})
```
Completion is triggered when typing inside double square brackets
or double braces, and the minimum number of characters to type before
completion can be configured. Multi-word completion is supported, so
completions will be suggested when typing more than one word inside the
brackets, together with a hint of the full page name.
When inserting a template, semantic completion of parameter names is provided,
and the documentation for each parameter is provided in the floating window,
based on the
[TemplateData](https://www.mediawiki.org/wiki/Extension:TemplateData) API.
You can refer to the relevant [upstream
documentation](https://github.com/neoclide/coc.nvim/wiki/Completion-with-sources)
to configure the source in coc.nvim. Settings can be defined in the
[coc-settings.json](https://github.com/neoclide/coc.nvim/wiki/Using-the-configuration-file):
```json
{
"coc": {
"source": {
"mediawiki": {
"enable": true,
"priority": 99
}
}
}
}
```
To further configure completion, see the [following
section](#Completion).
If you do not use coc.nvim, you may be able to use the function
`coc#source#mediawiki#complete()` to implement an
[omnifunc](https://vimhelp.org/options.txt.html#%27omnifunc%27), or to write an
adapter to plug it in other completion mechanisms. Please refer to the
[upstream documentation of the
API](https://github.com/neoclide/coc.nvim/wiki/Create-custom-source) used by
this source.
Snippets
========
Snippets in the [UltiSnips](https://github.com/SirVer/ultisnips) format are
shipped with this plugin, and they should work out-of-the-box if UltiSnips is
installed and configured. UltiSnips snippets can be used in coc.nvim through
the [coc-ultisnips source](https://github.com/neoclide/coc-sources).
Please note that this plugin aims to be site-agnostic, therefore no snippets
are shipped for specific sites, e.g. common templates used on the English
Wikipedia. Snippets of such kind are out of the scope of this project, but can
be easily defined in your own configuration, please refer to the [upstream
documentation](https://github.com/SirVer/ultisnips/blob/master/doc/UltiSnips.txt)
for more information.
Text objects
============
The plugin provides a set of text objects:
* `(mediawiki-text-object-inside-tick)` and
`(mediawiki-text-object-around-tick)` to operate inside or around
italic and bold markers
* `(mediawiki-text-object-inside-heading)` and
`(mediawiki-text-object-around-heading)` to operate inside or around
headings
* `(mediawiki-text-object-inside-pipes)` and
`(mediawiki-text-object-around-pipes)` to operate inside or around
pipes (e.g. positional template arguments)
* `(mediawiki-text-object-inside-link-page)` and
`(mediawiki-text-object-around-link-page)` to operate inside or around
the leftmost part of a link (between `[[` and `|`), containing the page of a
link
* `(mediawiki-text-object-inside-link-name)` and
`(mediawiki-text-object-around-link-name)` to operate inside or around
the rightmost part of a link (between `|` and `]]`), containing the name of a
link
* `(mediawiki-text-object-inside-template-begin)` and
`(mediawiki-text-object-around-template-begin)` to operate inside or around
the leftmost part of a template (between `{{` and `|`)
* `(mediawiki-text-object-inside-template-end)` and
`(mediawiki-text-object-around-template-end)` to operate inside or around
the rightmost part of a template (between `|` and `}}`)
* `(mediawiki-text-object-inside-named-argument)` and
`(mediawiki-text-object-around-named-argument)` to operate inside or around
a named argument (between `=` and `|`, where `|` is always excluded from the
text object)
The `` mappings can be associated to key mappings, for instance:
```viml
vmap i' (mediawiki-text-object-inside-tick)
vmap a' (mediawiki-text-object-around-tick)
omap i' (mediawiki-text-object-inside-tick)
omap a' (mediawiki-text-object-around-tick)
```
Surround
========
If [vim-surround](https://github.com/tpope/vim-surround) is installed, mappings
are created to surround text with wiki-link or template double-brackets, or
with bold or italic ticks. The characters bound to the surround map can be
configured with the variables
```viml
let g:vim_mediawiki_surround_wikilink = 'l'
let g:vim_mediawiki_surround_template = 't'
let g:vim_mediawiki_surround_bold = 'b'
let g:vim_mediawiki_surround_italic = 'i'
```
and can be disabled by setting
```viml
let g:vim_mediawiki_surround = 0
```
Configuration
=============
A set of variables allows to customise the behaviour of the plugin. All
variables can either be set globally as `g:vim_mediawiki_...` or locally for
each buffer with `b:vim_mediawiki_...`.
## Site
The value of `g:vim_mediawiki_site` sets the address of the wiki to edit.
The default is an empty string, and you need to set this in order to use
features such as auto-completion. Example:
```viml
let g:vim_mediawiki_site = 'en.wikipedia.org'
```
Site-specific options are stored in dictionaries, allowing to map different
settings to different sites for each buffer, according to the value of
`b:vim_mediawiki_site`. It is possible to automatically map custom file
extensions to site-specific settings by creating a custom
`ftdetect/mediawiki.vim`. For instance, to map files with extension `*.enwiki`
to settings specific for the English language Wikipedia:
```viml
autocmd BufRead,BufNewFile *.enwiki
\ set filetype=mediawiki |
\ let b:vim_mediawiki_site = 'en.wikipedia.org' |
\ set spelllang=en
```
## Completion
It is possible to customise which
[namespaces](https://www.mediawiki.org/wiki/Help:Namespaces) to auto-complete.
The configuration is stored on a per-site basis in a dictionary called
`g:vim_mediawiki_completion_namespaces`, whose keys are possible values of
`g:vim_mediawiki_site`. Each site is mapped to a dictionary, that associates
each trigger sequence to the number of the corresponding namespace on that
site. Example:
```viml
let g:vim_mediawiki_completion_namespaces = {
\ 'en.wikipedia.org': {
\ '[[': 0,
\ '{{': 10,
\ },
\ 'sv.wikipedia.org': {
\ '[[': 0,
\ '[[File:': 6,
\ '[[Kategori:': 14,
\ },
\ }
```
Only the namespaces listed in this map will be completed. A `default` entry is
used for sites not present among the keys. The pre-defined configuration is
```viml
let g:vim_mediawiki_completion_namespaces = {
\ 'default': {
\ '[[': 0,
\ },
\ }
```
and the custom configuration is merged with it, so the `default` key is
present unless it is overridden. Moreover, the buffer-local configuration is
merged with the global configuration, so it is not necessary to duplicate the
whole configuration in buffer-local variables, but it is sufficient to add or
overwrite only the desired sites. To disable completion for a site, map it to
an empty dictionary.
A complete configuration to edit the English language Wikipedia
[would be](https://en.wikipedia.org/wiki/Wikipedia:Namespace):
```viml
let g:vim_mediawiki_completion_namespaces = {
\ 'en.wikipedia.org': {
\ '[[': 0,
\ '[[Talk:': 1,
\ '[[User:': 2,
\ '[[User talk:': 3,
\ '[[Wikipedia:': 4,
\ '[[Wikipedia talk:': 5,
\ '[[File:': 6,
\ '[[:File:': 6,
\ '[[File talk:': 7,
\ '[[MediaWiki:': 8,
\ '[[MediaWiki talk:': 9,
\ '[[Template:': 10,
\ '{{': 10,
\ '[[Template talk:': 11,
\ '[[Help:': 12,
\ '[[Help talk:': 13,
\ '[[Category:': 14,
\ '[[:Category:': 14,
\ '[[Category talk:': 15,
\ '[[Portal:': 100,
\ '[[Portal talk:': 101,
\ '[[Book:': 108,
\ '[[Book talk:': 109,
\ '[[Draft:': 118,
\ '[[Draft talk:': 119,
\ '[[TimedText:': 710,
\ '[[TimedText talk:': 711,
\ '[[Module:': 828,
\ '[[Module talk:': 829,
\ },
\ }
```
The value of `g:vim_mediawiki_completion_prefix_length` determines the minimum
number of characters required after the trigger sequence to trigger completion.
Default:
```viml
let g:vim_mediawiki_completion_prefix_length = 5
```
The value of `g:vim_mediawiki_completion_limit` determines how many suggestions are
fetched. Default:
```viml
let g:vim_mediawiki_completion_limit = 15
```
## Preview
The command `MediaWikiPreview` generates a preview of the page being edited,
and loads it in a web browser window. It is possible to customise the command
used to open the browser, by setting
```viml
let g:vim_mediawiki_browser_command = "chromium \r"
```
where the carriage return character `\r` will be replaced with the address of
the page to open (attention should be paid to insert an actual carriage return
character, and to not escape the backslash).
## Mappings
No mappings are set out-of-the-box. The following optional navigation mappings
```viml
noremap j gj
noremap k gk
noremap 0 g0
noremap ^ g^
noremap $ g$
nnoremap D dg$
nnoremap C cg$
nnoremap A g$a
```
that help navigating wrapped lines can be enabled by setting to true the
variable
```viml
let g:vim_mediawiki_mappings = 1
```
## Syntax highlighting
Languages within `` or `` tags will be highlighted. A
list of languages (identified by their wiki name) to be ignored can be set:
```viml
let g:vim_mediawiki_ignored_wikilangs = ['cobol', 'pascal']
```
Syntax highlight settings are loaded for the languages detected within the
buffer at load or save time. Language settings can be preloaded for selected
languages:
```viml
let g:vim_mediawiki_preloaded_wikilangs = ['c', 'python']
```
A language name can be remapped to a different vim syntax highlighting:
```viml
let g:vim_mediawiki_wikilang_map = {'c': 'cpp'}
```
Credits and license
===================
The `syntax/mediawiki.vim` file is based on code originally published on
[Wikipedia:Text editor
support](http://en.wikipedia.org/wiki/Wikipedia:Text_editor_support) as public
domain, and distributed within the plugins
[wikipedia.vim](https://www.vim.org/scripts/script.php?script_id=1787) and
[mediawiki.vim](https://www.vim.org/scripts/script.php?script_id=3970).
The `ftplugin/mediawiki.vim` file contains some portions of code from the [HTML
ftplugin](https://github.com/vim/vim/blob/946e27ab65/runtime/ftplugin/html.vim#L28-L35)
of the vim runtime, by Johannes Zellner and Benji Fisher, and from
[mediawiki.vim](https://github.com/chikamichi/mediawiki.vim) by Jean-Denis
Vauguet (a.k.a. chikamichi).
The `autoload/mediawiki/fenced_languages.vim` file is adapted from
[mediawiki.vim](https://github.com/chikamichi/mediawiki.vim/blob/26e573726/autoload/mediawiki.vim)
by Olivier Teulière (a.k.a. ipkiss42).
All the original parts of this software, where not differently attributed or
licensed, are distributed under the MIT license. The full text of the license
is available in the [LICENSE
file](https://github.com/m-pilia/vim-mediawiki/blob/master/LICENSE) distributed
alongside the source code.