Open main menu

Extension:MintyDocs

MediaWiki extensions manual
OOjs UI icon advanced.svg
MintyDocs
Release status: stable
Implementation Parser function
Description An extension that allows for using a wiki for product documentation.
Author(s) Yaron Koren <yaron57@gmail.com>
Latest version 0.5 (July 2019)
Compatibility policy master
MediaWiki 1.25+
License GNU General Public License 2.0 or later
Download See here
Translate the MintyDocs extension if it is available at translatewiki.net
Check usage and version matrix.
Issues Open tasks · Report a bug

MintyDocs is a MediaWiki extension that can be used for product documentation. It is based conceptually in large part on the PonyDocs extension, though the underlying code is totally different. In MintyDocs (as in PonyDocs), wiki pages can be defined as being of one of four types: product, version, manual or topic. A version page must be a subpage of a product page, while a manual page must be a subpage of a version page. Topic pages, for the most part, should be subpages of manual pages, although a topic can also be defined as being "standalone".

MintyDocs also allows for drafting, by defining a "Draft:" namespace. Pages in the draft namespace can be "published" into the main namespace, so that, for instance, the contents of the page "Draft:ABC" can be published to the page "ABC". If the page "Draft:ABC" exists, the page "ABC" will be read-only, ensuring that there are no conflicting changes.

Download and installationEdit

You can download the MintyDocs code, in .zip format, here.

You can also download the code directly via Git from the MediaWiki source code repository. From a command line, you can call the following:

git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/MintyDocs.git

(To view the code online, including version history for each file, go here.)

Then, in the file 'LocalSettings.php', add the following line:

wfLoadExtension( 'MintyDocs' );

AuthorsEdit

MintyDocs was written by Yaron Koren.

Defining structuresEdit

There are four basic types of pages within MintyDocs: product, version, manual and topic.

To define a new product page, you just need to add a call to #mintydocs_product to that page, directly or via a template.

A version page must be a subpage of a product page; an example would be "Product X/1.0".

A manual page must be a subpage of a version page; an example would be "Product X/1.0/Getting started".

Topic pages are usually a subpage of a manual page; an example would be "Product X/1.0/Getting started/Installing the software". However, topic pages can actually be placed anywhere; a topic can be used as a "standalone topic", so that it can be included in more than one manual.

InheritanceEdit

One important feature of MintyDocs is inheritance: that is, you can have a page for a manual or topic simply display the contents of the same manual or topic for a previous version.

Let's say that you have three versions for a product: 1.0, 1.1 and 2.0. All three contain a manual called "Getting started". If this manual for version 1.0 is fully defined, then the page for the "Getting started" manual for version 1.1 can simply contain the following text:

{{#mintydocs_manual:
inherit
}}

It will then display the same content as the version 1.0 "Getting started". Or you can add additional parameters to the #mintydocs_manual call - these will take effect, while everything that is not specified will be inherited.

The same goes for the manual in version 2.0 - if such a page is set to inherit, the code will go backward through the versions until it finds the first non-inheriting manual page (in this case, for 1.0) and inherit the content and settings from that.

This same logic applies to topic pages as well, which can also inherit from "earlier" topic pages.

User permissionsEdit

For any product, there are four permission levels:

  • admin - can view and edit all pages for the product
  • editor - can view and edit all pages for the product, except for versions marked "closed"
  • previewer - can edit all pages for versions marked "released", can view all versions except those marked "closed"
  • the default level - can view and edit all pages for the product, for versions marked "released"

There are two ways to be assigned to a specific permission level for a product: either have that permission set across the entire wiki, via user group permissions; or have it set for a particular product, via a setting in the main page for that product.

For user group permissions, there are three relevant permissions: mintydocs-administer, mintydocs-edit and mintydocs-preview. By default, mintydocs-administer is set for the 'sysop' user group; that is the only default setting.

To create a new user group, let's say "md-editors", that are "editors" for all MintyDocs products, you could add the following line to LocalSettings.php:

$wgGroupPermissions['md-editors']['mintydocs-edit'] = true;

Product-specific user permissions are set within the call to #mintydocs_product; see below.

Parser functionsEdit

Five parser functions are defined for MintyDocs: #mintydocs_product, #mintydocs_version, #mintydocs_manual, #mintydocs_topic and #mintydocs_link. The first four of these functions, when called from a page, define that page as being of a certain type; these functions also have other parameters that set various attributes of that page. These four parser functions can be placed directly on a page, or (as is recommended) can be placed within a template that is then called from various pages.

The last function, #mintydocs_link, displays a link to another page within the MintyDocs system.

mintydocs_productEdit

#mintydocs_product defines a product page. It is called with the following parameters:

  • display name= - sets the display title for this page
  • admins= - takes in a comma-separated list of usernames and makes them "admins" for this product; see "User permissions", above
  • editors= - takes in a comma-separated list of usernames and makes them "editors" for this product
  • previewers= - takes in a comma-separated list of usernames and makes them "previewers" for this product

mintydocs_versionEdit

#mintydocs_version defines a version page. It is called with the following parameters:

  • status= - should be one of Released, Unreleased and Closed (Unreleased is the default).
  • manuals list= - holds a comma-separated list of the manuals for this version.

mintydocs_manualEdit

#mintydocs_manual defines a manual page. It is called with the following parameters:

  • display name= - sets the display title for this page
  • topics list= - holds a bulleted hierarchy of topic names. Names that begin with a "!" are considered "standalone topics" - these are topic pages that are not defined as being part of any manual, and their full page name must be specified. Names that begin with a "+" are considered "borrowed topics" - these are topic pages that belong to a different manual. For these pages, too, their full name/path must be specified. Names that begin with "-" are not treated as topic names, but simply as text. Any "topic name" that does not correspond to a topic is shown as a red link.
  • topics list page= - holds the name of a page that in turns holds a bulleted hierarchy, using the syntax described above. Only one of this parameter and "topics list=" should be specified.
  • pagination
  • inherit - takes no value; if it is specified, this page's contents come from the corresponding topic in an earlier version; see "Inheritance", above.
  • default form= - holds the name of a Page Forms form that is linked to for any red-linked topic in the topics list.
  • alternate forms= - holds a comma-separated list of "alternate forms" (again, defined by the Page Forms extension) for editing any red-linked topics.

mintydocs_topicEdit

#mintydocs_topic defines a topic page. It is called with the following parameters:

  • display name= - sets the display title for this page
  • toc name= - sets the display title for this page within the manual's table of contents
  • inherit - takes no value; if it is specified, this page's contents come from the corresponding topic in an earlier version; see "Inheritance", below.

mintydocs_linkEdit

#mintydocs_link displays a link to another MintyDocs page. It is called with the following parameters:

  • product= - a product name
  • version= - a version number
  • manual= - a manual name
  • topic= - a topic name
  • standalone - if specified, indicates that this is a standalone topic being linked
  • link text= - the text for the link
  • context product= - specifies a "context product" to display for this page, different from the actual product it belongs to
  • context version= - similar to "context product"
  • context manual= - similar to "context manual"
  • html - if specified, generates the link in HTML instead of wikitext
  • fragment= - the fragment/"anchor" of the generated URL, i.e. the part after "#"

At least one of the first four parameters must be set. The "lowest" parameter that is set determines what kind of page is being linked to. For example, if "manual=" is set but "topic=" is not, a manual page will be linked to.

Whatever parameters are not set, above the "lowest" one, will instead get their values from the page on which #mintydocs_link is called. So, for example, if a page called "Product X/1.0/Getting started/Installing the software" contains the following call:

{{#mintydocs_link:version=1.1|manual=Starting the engine}}

...then the call will display a link to the page "Product X/1.1/Starting the engine".

Page variablesEdit

MintyDocs defines the following three "variables", which can only be used on pages that are part of the MintyDocs structure:

  • {{MINTYDOCSPRODUCT}} - displays the name of the product for this page
  • {{MINTYDOCSVERSION}} - displays the name of the version for this page
  • {{MINTYDOCSMANUAL}} - displays the name of the manual for this page

DraftingEdit

You can optionally have some or all of the wiki's content have corresponding "draft" pages - whether or not they are MintyDocs pages. A page called "ABC" will have a draft page at "Draft:ABC". Any draft page will have a "Publish" tab, which can be used to populate the corresponding live/"published" page with the current contents of that draft page. A draft page for a MintyDocs product, version or manual will additionally let you publish all the child pages of that page.

For pages that don't yet have a draft page, but for which you want to create a draft page, you can go to Special:MintyDocsCreatePage/PageName and create that draft page or pages. It works essentially the same as "publishing", but going the other way, and it can only be done if the target page does not exist yet.

MintyDocs and PonyDocsEdit

Though MintyDocs borrows quite a bit of its approach to page structuring from PonyDocs, the two extensions differ substantially in their implementation. PonyDocs may be abandoned software at this point (it has not been actively maintained since early 2017), so this may be a pointless comparison, but nevertheless here are some major differences between the two extensions:

  • PonyDocs does URL rewriting (requiring changes to the Apache configuration), whereas MintyDocs does not.
  • PonyDocs requires all pages to be subpages of the page "Documentation/", whereas in MintyDocs pages can be placed anywhere.
  • PonyDocs generates additional user groups for each product, whereas MintyDocs does not.
  • In PonyDocs, there are additional pages for storing information about tables of contents, etc., while in MintyDocs all information is stored in the product, version etc. pages.
  • PonyDocs requires a top-line header (surrounded with '=') at the top of every page, whereas MintyDocs does not - this enables MintyDocs to be used together with the Page Forms extension.
  • PonyDocs is available only in English, whereas MintyDocs is fully translated.

Version historyEdit

  • 0.1 - June 28, 2018 - Initial version
  • 0.2 - October 18, 2018 - Added "Draft:" namespace and publishing; added "-" syntax to topics list for #mintydocs_manual; added "link text" param to #mintydocs_link; bug fixes
  • 0.3 - November 15, 2018 - Added Page Forms params to #mintydocs_manual; bug fixes
  • 0.4 - February 12, 2019 - Removed $wgMintyDocsProductPages global variable; added "placeholder" param to #mintydocs_link; made "unreleased" the default status; made version status case-insensitive; added "parent pages" to publishing interface; avoid "publishing" pages before their parents are published; ignore red-linked topics in non-draft manuals; bug fixes
  • 0.5 - July 24, 2019 - Added Special:MintyDocsDelete; added Special:MintyDocsCopy; added "mintydocspublish" API action; added parameters "context product", "context version", "context manual", "html" and "fragment" to #mintydocs_link; added "borrowed" topic concept, using "+" in TOC; made manual page the first "topic" in its TOC; added $wgMintyDocsShowBreadcrumbs global variable; added "(de)select all" links to MintyDocsPublish, etc.; added "single" query string parameter for MintyDocsPublish and MintyDocsCopy; made page listing in MintyDocsPublish, etc. resemble TOC hierarchy; disabled viewing of draft pages by non-MintyDocs users; bug fixes