Summary: An enhanced page editor for PmWiki
Status: Release Candidate
Prerequisites: pmwiki-2.2+, CodeMirror
v4.8+ (defaults to v5.15.2), PHP 5.2+ and a recent browser
(helped by Simon
- An enhanced page editing experience with pmwiki syntax highlighting, line numbers and line wrapping,
- A generic syntax highlighting renderer for your source code excerpts, including PmWiki's own while using
- Download the CodeMirror archive from its distribution site
- Extract it in a folder in your
pub/ directory, e.g.
- Extract the recipe archive at the root of your PmWiki installation, putting the two php files in the
cookbook/ directory and the
cm/ folder containing js/css files in the
This should end with something like:
+- codemirror.php <--+
+- cm-sourceblock.php <--+--[recipe stuff]
+- cm/ <--+
| +- ...
+- codemirror-5.15.2 <-----[CodeMirror distribution]
- Enable the recipe in your Local Customizations by including the recipe script:
- If different from defaults, locate the codemirror distribution before the
include_once in Local Customizations,
e.g. for distribution
$CodeMirrorBaseUrl = "\$FarmPubDirUrl/codemirror-5.1";
- Then, navigate to a wiki page and edit it to see the component in action.
When enabled, the usual editing graphical buttons are made fully compatible with the new editor.
A trailing checkbox is automatically added to the toolbar, allowing to switch back and forth between the codemirror editor and the regular textarea.
As provided by the recipe, the CodeMirror component is configured with some active presets:
- Top and bottom borders (
- Line numbers display, line wrapping (
- Syntax highlighting (
- Text selection compatible with styled background text (
- Cursor color change according to insertion mode (
- Active line background (
- Visual tabulation (
- Visual trailing spaces (
trailingspace), inactive by default
- Regular Tab key focus handling (
- Automatic continuation of (Un)ordered lists (
- Autosize editor area according to content (
autoresize) or up to specified height (
maxheight). These are inactive by default and shouldn't be used together.
- Full screen editing (
fullscreen), inactive by default. Pressing F11 when cursor is in the editor will toggle full screen editing (Esc can also be used to exit).
- Search and replace (
search), inactive by default (you may refer to CodeMirror search demo for related keybindings).
- Autocompletion (
hint), inactive by default. Pressing Ctrl-Space will simply looks at nearby words in the buffer and completes to those.
These customizations could be easily managed in the configuration file by setting them before including the recipe main script:
$CodeMirrorActivePresets['linenumbers'] = 0; # no line numbers
$CodeMirrorActivePresets['activeline'] = 0; # no highlighting for active line
$CodeMirrorActivePresets['maxheight'] = 1;
$CodeMirrorPresetParams['maxheight'] = '30em';
- Some presets are based on addons included in the CodeMirror distribution and therefore they should be included (if needed) when getting the distribution in a minified form.
The following variables are available to customize the recipe installation and behaviour:
- Defaults to
'codemirror.js', ie. it provides a way to easily reference a minified version of the CodeMirror script.
- As the recipe is dynamically binding CodeMirror's addons and modes sub-scripts according to the context, there's no need to merge other scripts when generating a minified version of the main script.
- Respectively, selector, repository and related parameters of combinated data automatically added to the 3 following variables.
- PlaceHolders in
where CodeMirror addon scripts and custom styles could be defined.
- Entry point to the CodeMirror configuration object content itself.
- Global switches for the 2 recipe main parts.
- Global switch for the
Code source highlighting
After an initial configuration step (needed each time the CodeMirror distribution is upgraded), the recipe provides the following markup for your code exercepts:
(:code <parameters>:) [@
with the following parameters:
modelist will list inconditionnaly all the differents language modes and mime/types offered by the CodeMirror component.
<mode / mime> is the CodeMirror mode or mime/type to use for highlighting the code block.
linenum(=n) would activate the rendering as an ordered list, optionally starting at the specified number.
More details on the initialisation step in the next section.
Caveats / Known limitations
As the PmWiki language is a very convenient markup set for the user, writing a syntaxic highlighter for it is rather hard.
The one provided here is far from perfect, but should be able to render most of the language features.
Its main limitation is to be only able to handle upper level markups: ie. the markup sequence
''some [[Page]]'' would only be recognized as emphasized text, ignoring the inner link definition.
Another noticeable flaw is the lack of spell checking in the highlighted editor.
This intrinsic limitation of CodeMirror and its way of handling text is the main reason to have available the highlight/regular edting checkbox feature in the icons bar.
The syntax colors/styles proposed for the PmWiki markup really need to be improved.
In order to handle all CodeMirror's highlighting languages subscripts and properly handle their inter-dependencies, the recipe need to build and maintain a configuration file describing them. The first time some source code is given to the recipe in a page, a link is provided to generate the required file (
cm-modes-dependencies.php located in the
The next time while the CodeMirror distribution is upgraded, the configuration file can be safely erased (and regenerated by the reappearing link), or directly rebuild using the
?action=cm-dependencies url parameter.
Change log / Release notes
- 2016-05-27 Added more presets. Some fixes in highlighting enabling title variable sizing.
- 2016-05-26 Added mime/type handling in source code highlighting. Added search preset.
- 2016-05-24 Synched recipe default to v5.12.2 distribution. Merged Simon's latest highlighting styles and definitions. Fixed
- 2015-04-12 Added more suggested updates to markup handling. Modified presets to simplify configuration.
- 2015-03-29 Added suggested fixes and updates to markup handling. Extraneous (buggy) development files left in
pub/cm/ folder by previous release are unused should be removed (oops).
- 2015-03-27 Synched recipe default to v5.1 distribution. Remove forgotten debugging code making the recipe crash in some cases.
- 2015-03-12 Synched recipe default to v4.13 distribution. Enabled source code highligting for intermixed languages.
- 2015-01-20 Synched recipe default to v4.11 distribution. Fixed missing highlighting, added lists continuation and
- 2014-12-26 Added missing MarkupExpr highlighting
- 2014-12-23 Major rewrite with effective syntax highlighting
- 2013-03-11 First public release
Recipe written by Dfaure and Simon, maintained by Dfaure.
See discussion at CodeMirror-Talk
User notes +4: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.