Jump to content

Extension:MintyDocs

Issue tracker: #MediaWiki-extensions-MintyDocs
From mediawiki.org
Translate this page
Languages:
MediaWiki extensions manual
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 1.2.1 (April 2024)
Compatibility policy Master maintains backward compatibility.
MediaWiki 1.37+
License GNU General Public License 2.0 or later
Download
Download extension
Git [?]:
See here
Parameters
  • $wgMintyDocsShowBreadcrumbs
  • $wgMintyDocsDisplayFooterElementsInSidebar
Added rights
  • mintydocs-administer
  • mintydocs-edit
  • mintydocs-editlive
Hooks used
Quarterly downloads 0
Translate the MintyDocs extension if it is available at translatewiki.net
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 now-obsolete 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 installation

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' );


Authors

MintyDocs was written by Yaron Koren.

Defining structures

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.

Inheritance

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 permissions

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.

MintyDocs defines four user permissions:

  • mintydocs-administer - provides admin permission across all products
  • mintydocs-edit - provides editor permission across all products
  • mintydocs-editlive - provides the permission to edit "live" pages (pages in the main namespace), even when a draft page exists for them, across all products
  • mintydocs-preview - provides previewer permission across all products

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 functions

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_product

#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_version

#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_manual

#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_topic

#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_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 product"
  • 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 variables

MintyDocs defines the following "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
  • {{MINTYDOCSDISPLAYNAME}} - displays the defined "display name" for this page

Drafting

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:MintyDocsCreateDraft/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.

Page Forms input for topics list

The "mintydocs toc" Page Forms input type

It can be helpful to make wrapper templates around the four main content type parser functions, so that the pages that call them can be edited using the Page Forms extension. This is especially helpful for the #mintydocs_manual function, which has the most complicated syntax. If you are using a template and form for manual pages, then the template parameter that corresponds to "topics list" can be edited using the "mintydocs toc" input type (an input type defined in MintyDocs), by adding "|input type=mintydocs toc" to that field's tag in the form definition.

This input type lets you create the whole hierarchical topics list by adding, deleting, moving and renaming rows within the tree. The one thing it unfortunately does not let you do yet is modifying entry types, between the four allowed types (regular topics, standalone topics, borrowed topics and text entries). You can, however, do this with a hack: if you have an entry representing a regular topic, you can turn it into one of the three other types (standalone, borrowed, text entry) by adding a "!", "+" or "-", respectively, to the beginning of the page name.

Version history

  • 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
  • 0.6 - February 28, 2020 - Added "mintydocs toc" Page Forms input type; improved handling for MW 1.34+; bug fixes
  • 0.7 - May 1, 2020 - Removed support for MW < 1.29; improved support for MW >= 1.32; fixed Special:MintyDocsCopy to always copy to correct namespace; made "Draft" and "Draft talk" namespaces non-searchable for users without special permissions; some file renaming; other fixes
  • 0.7.1 - June 26, 2020 - Added 'noindex' to all Draft pages; disabled checkbox for pages whose parent is unpublished in Special:MintyDocsPublish; improved handling for MW 1.32+
  • 0.8 - January 26, 2021 - Added "mintydocs-editlive" permission; added MINTYDOCSDISPLAYNAME variable; set Publish/Copy/CreateDraft special pages to only operate on pages whose parent page already exists; made standalone draft topics unreadable for unauthorized users; fix for #mintydocs_link call within standalone topics; fix for lowercase usernames in #mintydocs_product; fix for underscores in topic names in TOC; improved handling for MW 1.35+; other fixes
  • 0.8.1 - June 24, 2021 - Modified interface to use OOUI; added "target product" and "target manual" options for Special:MintyDocsCopy; fixed handling for MW 1.36+; other fixes
  • 0.9 - December 13, 2021 - Removed support for MW < 1.32; improved support for MW 1.34+; other fixes
  • 1.0 - January 26, 2023 - Removed support for MW < 1.34; improved support for MW 1.38+
  • 1.1 - May 19, 2023 - Removed support for MW < 1.35; made some special pages unlisted
  • 1.2 - January 25, 2024 - Removed support for MW < 1.37; improved support for MW 1.39+
  • 1.2.1 - April 15, 2024 - Fixed handling for MW 1.40+
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:MintyDocs/en&oldid=6471077"