Difference between revisions of "Visual editor"

From Freephile Wiki
Jump to navigation Jump to search
(Updated for 2023)
m
(45 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Feature
+
The [http://www.mediawiki.org/wiki/VisualEditor Visual Editor] for MediaWiki relies on the '''[[mw:Extension:Parsoid|Parsoid]]''' extension <ref>[https://git.wikimedia.org/tree/mediawiki%2Fextensions%2FParsoid Parsoid extension]</ref> AND the Parsoid service.  The Parsoid service is a node.js server that interacts with the mediawiki API.
|image=Visual Editor (linking).png
 
|imgdesc=Direct editing
 
|title=
 
}}
 
{{#set:feature description = A reliable rich-text editor for MediaWiki. Allows you to just "edit the page you see" while being aware of all the syntactically rich features of templates, extensions etc.}}
 
{{#set:feature notes = The Visual Editor is available Here and on Wikipedia.}}
 
{{#set:feature tests = [[Special:UserLogin|Login]] to the wiki, and make an edit in your [[Special:MyPage/Sandbox|personal sandbox]]. }}
 
{{#set:feature examples = }}
 
  
 +
<blockquote>"Parsoid implements a bidirectional wikitext parser and interpreter. It converts and interprets wikitext into an annotated HTML DOM, which can then be edited with HTML editor tools such as the Visual Editor. It also provides the conversion of a (possibly modified) HTML DOM back to wikitext."</blockquote>
  
[[File:VisualEditor-logo.svg|alt=Visual Editor|frameless|641x641px|Visual Editor logo]]
+
Robin Cover would be proud.  It round-trips wiki to HTML + RDFa and back.
== Links ==
 
* [https://www.mediawiki.org/wiki/Help:VisualEditor/User_guide User Guide]
 
* [https://www.mediawiki.org/wiki/Project:Sandbox Demo] (no account needed)
 
* [https://www.mediawiki.org/wiki/VisualEditor/Portal/Help Portal to Help Content about VE]
 
  
== Back story ==
+
== Installation ==
Wiki markup is a sort of shorthand for more complicated HTML markup designed to create nicely formatted web documents.  Although in the beginning wiki markup simplified the process of creating nicely formatted content, that shorthand can get increasingly complex in order to produce complicated layout and content.  The extension of the markup system over time to include a template subsystem and macros inevitably leads to a tension between ease of use, and power.  This tension was one of the primary factors that the Wikimedia Foundation cited as an impediment to new content collaborators for the Wikipedia. <ref>https://strategy.wikimedia.org/wiki/March_2011_Update</ref><ref>http://strategy.wikimedia.org/wiki/Editor_Trends_Study</ref> <ref>See this October 2013 article in the MIT Technology Review http://www.technologyreview.com/featuredstory/520446/the-decline-of-wikipedia</ref>. A visual editor was deemed nearly impossible after many early attempts failed, but with the advent of Node.js technology, it became an idea that was plausible again.
+
You'll need at least [http://www.mediawiki.org/wiki/Release_notes/1.23 MediaWiki v1.23].  I personally run the same [http://www.mediawiki.org/wiki/Special:Version version that they're running on mediawiki.org] (1.24wmf3 [[User:Freephile|greg.rundlett]] ([[User talk:Freephile|talk]]) 19:39, 9 May 2014 (UTC))
 +
=== WebFaction ===
  
Fast-forward to 2016 when VisualEditor was fully working as a Visual WYSIWYG interface for editing MediaWiki content, using a Node.js backend called 'Parsoid' which is a bidirectional runtime wiki parser. This caused a big software architectural problem: there were two parsers to maintain: the 'normal' (now 'legacy') core parser in PHP, and the Visual Editor parser (Parsoid) in JavaScript. So, by the end of 2019, Parsoid was ported to PHP, and distributed with MediaWiki 1.35 as part of the [mw:Parsoid/Parser_Unification|Parser Unification initiative]].
+
To install the Visual Editor extension in a Webfaction account, you need to first have node installed and working.  You can do this by using the [http://docs.webfaction.com/software/custom.html installer in your webfaction panel] and associating a path with the app for a domain. I chose to install 'node' (which is now it's own one-click install) and also installing another 'app' to open up a port to use with the service. I had to export the PORT, but this is no longer necessary if you configure it in localsettings.js.  Depending on the resource constraints of your hosting package, you may need to limit the number of workers spawned by the Parsoid service. It calculates a number based on the number of processors.  For a shared hosting account, this is guaranteed to break, so specify the <code>--num-workers</code> option.
  
== Intro ==
+
Follow the installation instructions, and remember to edit both LocalSettings.php and localsettings.js
* [https://commons.wikimedia.org/w/index.php?title=File%3AWikimania_2013_-_VisualEditor_-_The_present_and_future_of_editing_our_wikis.webm VIDEO] Wikimania 2013
 
* [https://www.youtube.com/watch?v=M_Ioi1aLAL8 VIDEO] (47 min.) with James Forrester - Product Manager and Roan Kattouw - Sr. Software Engineer presenting Jan 13, 2014 at Linux.conf.au on the contentEditable aspects of the system.
 
  
The [http://www.mediawiki.org/wiki/VisualEditor Visual Editor] for MediaWiki relies on [[mw:Parsoid|Parsoid]]
 
  
<blockquote>"Parsoid implements a bidirectional wikitext parser and interpreter. It converts and interprets wikitext into an annotated HTML DOM, which can then be edited with HTML editor tools such as the Visual Editor. It also provides the conversion of a (possibly modified) HTML DOM back to wikitext."</blockquote>
+
You'll want to set/update your $NODE_PATH and $PATH environment variables to locate the installed node modules, and to find the node and npm binaries
 +
<source lang="bash">
 +
export NODE_PATH="$HOME/webapps/node/lib/node_modules:$NODE_PATH"
 +
echo 'export NODE_PATH="$HOME/webapps/node/lib/node_modules:$NODE_PATH"' >> $HOME/.bashrc
 +
which npm
 +
export PATH="$HOME/webapps/node/bin:$PATH"
 +
echo 'export PATH="/$HOME/webapps/node/bin:$PATH"' >> $HOME/.bashrc
 +
</source>
  
[http://xml.coverpages.org/ Robin Cover] would be proud.  It round-trips wiki to HTML + RDFa and back.
+
Once node (and npm) is available, you of course need to get the parsoid and visual_editor extensions. A quick <code>npm install</code> in the parsoid directory sets up all the node machinery.
  
== Installation ==
+
To have it run continuously, you might want to use the 'forever' module.
VisualEditor is included with MediaWiki. See https://www.mediawiki.org/wiki/Extension:VisualEditor
+
<source lang="bash">
 +
npm install -g forever
 +
cd ~/webapps/wiki/extensions/Parsoid/
 +
forever node api/server.js --num-workers=2 &
 +
</source>
  
  
Line 38: Line 36:
 
# [[mw:Extension:VisualEditor]]
 
# [[mw:Extension:VisualEditor]]
 
# [[mw:Extension:Parsoid]]
 
# [[mw:Extension:Parsoid]]
 
=== Extensions that hook into VE ===
 
* https://codesearch-beta.wmcloud.org/things/?q=ve.ui.commandRegistry.register&files=&excludeFiles=&repos=
 
* https://codesearch-beta.wmcloud.org/extensions/?q=VisualEditorPluginModules&i=nope&files=&repos=
 
 
Extension authors should register <code>VisualEditorPluginModules</code>
 
# https://www.mediawiki.org/wiki/Extension:Proofread_Page
 
# https://www.mediawiki.org/wiki/Extension:CodeMirror (syntax highlighting)
 
# https://www.mediawiki.org/wiki/Extension:Disambiguator
 
# https://www.mediawiki.org/wiki/Extension:Graph
 
# https://www.mediawiki.org/wiki/Extension:Kartographer (Open Street Maps)
 
# https://www.mediawiki.org/wiki/Extension:LanguageTool
 
# https://www.mediawiki.org/wiki/Extension:Math
 
# https://www.mediawiki.org/wiki/Extension:Score (LillyPond)
 
# https://www.mediawiki.org/wiki/Extension:SyntaxHighlight
 
# https://www.mediawiki.org/wiki/Extension:TemplateData
 
# https://www.mediawiki.org/wiki/Extension:WikiHiero
 
 
 
== Customizing Visual Editor with custom menus, tools, commands ==
 
* https://www.mediawiki.org/wiki/VisualEditor/Gadgets
 
* https://www.mediawiki.org/wiki/VisualEditor/Gadgets/Creating_a_custom_command
 
* https://www.mediawiki.org/wiki/VisualEditor/Gadgets/Add_a_tool
 
 
  
 
== API / Developer Docs / DevOps ==
 
== API / Developer Docs / DevOps ==
Line 71: Line 45:
 
* https://doc.wikimedia.org/VisualEditor/master/ powered by JSDuck
 
* https://doc.wikimedia.org/VisualEditor/master/ powered by JSDuck
 
* http://blog.gmane.org/gmane.science.linguistics.wikipedia.wikitext wikitext-l
 
* http://blog.gmane.org/gmane.science.linguistics.wikipedia.wikitext wikitext-l
 +
 +
I [https://gerrit.wikimedia.org/r/#/c/132479/1/api/ParsoidService.js noticed a bug] and it was fixed about 5 minutes after I mentioned it!  (Thanks C. Scott Ananian)
  
 
{{References}}
 
{{References}}
  
 
[[Category:Wiki]]
 
[[Category:Wiki]]
[[Category:JavaScript]]
 

Revision as of 16:02, 9 May 2014

The Visual Editor for MediaWiki relies on the Parsoid extension [1] AND the Parsoid service. The Parsoid service is a node.js server that interacts with the mediawiki API.

"Parsoid implements a bidirectional wikitext parser and interpreter. It converts and interprets wikitext into an annotated HTML DOM, which can then be edited with HTML editor tools such as the Visual Editor. It also provides the conversion of a (possibly modified) HTML DOM back to wikitext."

Robin Cover would be proud. It round-trips wiki to HTML + RDFa and back.

Installation[edit | edit source]

You'll need at least MediaWiki v1.23. I personally run the same version that they're running on mediawiki.org (1.24wmf3 greg.rundlett (talk) 19:39, 9 May 2014 (UTC))

WebFaction[edit | edit source]

To install the Visual Editor extension in a Webfaction account, you need to first have node installed and working. You can do this by using the installer in your webfaction panel and associating a path with the app for a domain. I chose to install 'node' (which is now it's own one-click install) and also installing another 'app' to open up a port to use with the service. I had to export the PORT, but this is no longer necessary if you configure it in localsettings.js. Depending on the resource constraints of your hosting package, you may need to limit the number of workers spawned by the Parsoid service. It calculates a number based on the number of processors. For a shared hosting account, this is guaranteed to break, so specify the --num-workers option.

Follow the installation instructions, and remember to edit both LocalSettings.php and localsettings.js


You'll want to set/update your $NODE_PATH and $PATH environment variables to locate the installed node modules, and to find the node and npm binaries

export NODE_PATH="$HOME/webapps/node/lib/node_modules:$NODE_PATH"
echo 'export NODE_PATH="$HOME/webapps/node/lib/node_modules:$NODE_PATH"' >> $HOME/.bashrc
which npm
export PATH="$HOME/webapps/node/bin:$PATH"
echo 'export PATH="/$HOME/webapps/node/bin:$PATH"' >> $HOME/.bashrc

Once node (and npm) is available, you of course need to get the parsoid and visual_editor extensions. A quick npm install in the parsoid directory sets up all the node machinery.

To have it run continuously, you might want to use the 'forever' module.

npm install -g forever
cd ~/webapps/wiki/extensions/Parsoid/
forever node api/server.js --num-workers=2 &


Extensions[edit | edit source]

  1. mw:Extension:VisualEditor
  2. mw:Extension:Parsoid

API / Developer Docs / DevOps[edit | edit source]

I noticed a bug and it was fixed about 5 minutes after I mentioned it! (Thanks C. Scott Ananian)

References[edit source]