Improve markdown files and add markdownlint

.github/workflows/pull-request-checks.yml

@@ -1,11 +1,17 @@
 name: "Pull Request Checks"
 on: pull_request
 jobs:
-  # Enforces the update of a changelog file on every pull request 
+  # Enforce the update of the changelog file
   check-changelog-change:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
     - uses: dangoslen/changelog-enforcer@v2
-      with:
-        versionPattern: '### (Version \\d+\\.\\d+\\.\\d* - \\d{4}-\\d{2}-\\d{2}|Upcoming version)'
+  # Ensure markdown files are formatted consistently
+  lint-markdown-files:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: xt0rted/markdownlint-problem-matcher@v1
+      - run: npm install -g markdownlint-cli
+      - run: markdownlint **/*.md

.markdownlint.yml

@@ -0,0 +1,26 @@
+# MD010/no-hard-tabs
+MD010:
+  # Exclude code blocks
+  code_blocks: false
+
+# MD013/line-length
+MD013:
+  # Custom length limit (default is 80)
+  line_length: 100
+  # Exclude code blocks
+  code_blocks: false
+
+# MD024/no-duplicate-heading
+MD024:
+  # Only check sibling headings
+  allow_different_nesting: true
+
+# MD026/no-trailing-punctuation
+MD026:
+  # Trailing punctuation characters not allowed in headings
+  punctuation: ",;:!"
+
+# MD004/ul-style
+MD004:
+  # Use dashes for lists, leaving asterisks for emphasis
+  style: "dash"

CHANGELOG.md

@@ -1,158 +1,161 @@
-## Changelog
+# Changelog
+
+This page lists the changes that were done in each version of Wikimate.
 
 Since v0.10.0 this project adheres to [Semantic Versioning](http://semver.org/)
 and [Keep a Changelog](http://keepachangelog.com/).
 
-### Upcoming version
+## Upcoming version
 
-#### Added
+### Added
 
-* New exception class `WikimateException` for API communication errors ([#136])
-* Usage documentation about maximum lag and retries ([#134])
-* New `CONTRIBUTING.md` file with contribution guidelines ([#135])
+- New exception class `WikimateException` for API communication errors ([#136])
+- Usage documentation about maximum lag and retries ([#134])
+- New GitHub Action to enforce updates to `CHANGELOG.md` ([#131])
+- New `CONTRIBUTING.md` file with contribution guidelines ([#135])
+- New GitHub Action to check markdown files ([#138])
 
-#### Changed
+### Changed
 
-* Centralized API communication checks in `WikiPage::request()` ([#136])
-* Added additional context to `README.md` ([#127])
-* Added semi-linear merge recommendation to `GOVERNANCE.md` ([#130])
-* Added GitHub Action to enforce updates to `CHANGELOG.md` ([#131])
+- Centralized API communication checks in `WikiPage::request()` ([#136])
+- Added additional context to `README.md` ([#127])
+- Added semi-linear merge recommendation to `GOVERNANCE.md` ([#130])
 
 _The following two entries are backwards incompatible API changes
 and may require changes in applications that invoke these methods:_
 
-* Error return values for `WikiPage::getSection()` changed from `false` to `null` ([#129])
-* `Wikimate::login()` error code `'login'` is now `'auth'`, also used by `logout()` ([#132])
+- Error return values for `WikiPage::getSection()` changed from `false` to `null` ([#129])
+- `Wikimate::login()` error code `'login'` is now `'auth'`, also used by `logout()` ([#132])
 
-#### Fixed
+### Fixed
 
-* Fixed one error return value in `WikiPage::setText()` ([#129])
-* Fixed exception type/message for `$keyNames` parameter to `WikiPage::getAllSections()` ([#133])
+- Fixed one error return value in `WikiPage::setText()` ([#129])
+- Fixed exception type/message for `$keyNames` parameter to `WikiPage::getAllSections()` ([#133])
 
-#### Removed
+### Removed
 
-* Method `Wikimate::debugCurlConfig()`, deprecated since v0.10.0 ([#128])
+- Method `Wikimate::debugCurlConfig()`, deprecated since v0.10.0 ([#128])
 
-### Version 0.15.0 - 2021-08-26
+## Version 0.15.0 - 2021-08-26
 
-#### Added
+### Added
 
-* New methods `WikiFile::revert()` and `Wikimate::filerevert()` ([#123])
-* New method `Wikimate::logout()` ([#124])
-* Added post-release update steps to `GOVERNANCE.md` ([#125])
+- New methods `WikiFile::revert()` and `Wikimate::filerevert()` ([#123])
+- New method `Wikimate::logout()` ([#124])
+- Added post-release update steps to `GOVERNANCE.md` ([#125])
 
-#### Changed
+### Changed
 
-* Updated `Wikimate::token()` to remember CSRF token and reduce API calls ([#122])
+- Updated `Wikimate::token()` to remember CSRF token and reduce API calls ([#122])
 
-#### Fixed
+### Fixed
 
-* Fixed format of user agent string ([#121])
+- Fixed format of user agent string ([#121])
 
-### Version 0.14.0 - 2021-08-24
+## Version 0.14.0 - 2021-08-24
 
-#### Added
+### Added
 
-* Support for the maxlag parameter (with retries) in API requests ([#112])
-* Support for getting/setting user agent for API requests ([#107])
-* Added missing PHPDoc comments for properties, constants, and more ([#109])
+- Support for the maxlag parameter (with retries) in API requests ([#112])
+- Support for getting/setting user agent for API requests ([#107])
+- Added missing PHPDoc comments for properties, constants, and more ([#109])
 
-#### Changed
+### Changed
 
-* Changed API requests from deprecated PHP format to JSON format ([#111])
-* Grouped sections and added table of contents in `USAGE.md` ([#108])
+- Changed API requests from deprecated PHP format to JSON format ([#111])
+- Grouped sections and added table of contents in `USAGE.md` ([#108])
 
-#### Fixed
+### Fixed
 
-* Removed null returns from destructors & fixed PHPDoc comments ([#114])
-* Fixed sections object initialization warning in PHP 7.4+ ([#118])
+- Removed null returns from destructors & fixed PHPDoc comments ([#114])
+- Fixed sections object initialization warning in PHP 7.4+ ([#118])
 
-### Version 0.13.0 - 2021-07-05
+## Version 0.13.0 - 2021-07-05
 
-#### Added
+### Added
 
-* Added more debug logging of MediaWiki requests and responses ([#101], [#106])
-* New `GOVERNANCE.md` file to explicitly codify the project management principles
+- Added more debug logging of MediaWiki requests and responses ([#101], [#106])
+- New `GOVERNANCE.md` file to explicitly codify the project management principles
   and provide guidelines for maintenance tasks ([#83], [#105])
 
-#### Changed
+### Changed
 
-* Modernized token handling for login and data-modifying actions.
+- Modernized token handling for login and data-modifying actions.
   Requires MediaWiki v1.27 or newer. ([#100], [#106])
 
-#### Fixed
+### Fixed
 
-* Prevented PHP notice in `WikiFile::getInfo()` for moved or deleted file ([#85])
-* Fixed capitalization of a built-in PHP class in a comment ([#106])
+- Prevented PHP notice in `WikiFile::getInfo()` for moved or deleted file ([#85])
+- Fixed capitalization of a built-in PHP class in a comment ([#106])
 
-### Version 0.12.0 - 2017-02-03
+## Version 0.12.0 - 2017-02-03
 
-#### Added
+### Added
 
-* New class WikiFile to retrieve properties of a file, and download and upload its contents.
+- New class WikiFile to retrieve properties of a file, and download and upload its contents.
   All properties pertain to the current revision of the file, or a specific older revision.
   ([#69], [#71], [#78], [#80])
-* WikiFile also provides the file history
+- WikiFile also provides the file history
   and the ability to delete a file or an older revision of it ([#76])
 
-### Version 0.11.0 - 2016-11-16
+## Version 0.11.0 - 2016-11-16
 
-#### Added
+### Added
 
-* Support for a section name (in addition to an index)
+- Support for a section name (in addition to an index)
   in `WikiPage::setText()` and `WikiPage::setSection()` ([#45])
-* Support for optional domain at authentication ([#28])
+- Support for optional domain at authentication ([#28])
 
-#### Changed
+### Changed
 
-* Updated `WikiPage::getSection()` to include subsections by default;
+- Updated `WikiPage::getSection()` to include subsections by default;
   disabling the new `$includeSubsections` option reverts to the old behavior
   of returning only the text until the first subsection ([#55])
-* Improved section processing in `WikiPage::getText()` ([#33], [#37], [#50])
-* Ensured that MediaWiki API error responses appear directly in `WikiPage::$error`
+- Improved section processing in `WikiPage::getText()` ([#33], [#37], [#50])
+- Ensured that MediaWiki API error responses appear directly in `WikiPage::$error`
   rather than a nested 'error' array.
   This may require changes in your application's error handling ([#63])
-* Restructured and improved documentation ([#32], [#34], [#47], [#49], [#61])
+- Restructured and improved documentation ([#32], [#34], [#47], [#49], [#61])
 
-#### Fixed
+### Fixed
 
-* Ensured use of Wikimate user agent by Requests library ([#64])
-* Corrected handling an invalid page title ([#57])
-* Fixed returning an empty section without header in `WikiPage::getSection()` ([#52])
-* Prevented PHP Notices in several methods ([#43], [#67])
-* Corrected handling an unknown section parameter in `WikiPage::getSection()` ([#41])
-* Fixed passing the return value in `WikiPage::setSection()` ([#30])
-* Corrected call to `Wikimate::debugRequestsConfig()` ([#30])
+- Ensured use of Wikimate user agent by Requests library ([#64])
+- Corrected handling an invalid page title ([#57])
+- Fixed returning an empty section without header in `WikiPage::getSection()` ([#52])
+- Prevented PHP Notices in several methods ([#43], [#67])
+- Corrected handling an unknown section parameter in `WikiPage::getSection()` ([#41])
+- Fixed passing the return value in `WikiPage::setSection()` ([#30])
+- Corrected call to `Wikimate::debugRequestsConfig()` ([#30])
 
-### Version 0.10.0 - 2014-06-24
+## Version 0.10.0 - 2014-06-24
 
-#### Changed
+### Changed
 
-* Switched to using the *Requests* library instead of Curl ([#25])
+- Switched to using the *Requests* library instead of Curl ([#25])
 
-### Version 0.9 - 2014-06-13
+## Version 0.9 - 2014-06-13
 
-* Bumped version for stable release
+- Bumped version for stable release
 
-### Version 0.5 - 2011-09-09
+## Version 0.5 - 2011-09-09
 
-* Removed the use of constants in favour of constructor arguments
-* Added checks that throw an exception if can't write to wikimate_cookie.txt
-* Throws exception if curl library not loaded
-* Throws exception if can't login
+- Removed the use of constants in favour of constructor arguments
+- Added checks that throw an exception if can't write to wikimate_cookie.txt
+- Throws exception if curl library not loaded
+- Throws exception if can't login
 
-### Version 0.4 - 2011-01-15
+## Version 0.4 - 2011-01-15
 
-* Added `WikiPage::newSection()` and `WikiPage::setSection()` (shortcuts to `WikiPage::setText()`)
-* Added the ability to get individual sections of the article with `WikiPage::getSection()`
-* Added the ability to get all sections in an array with `WikiPage::getAllSections()`
-* Added the ability to get an array showing section offsets and lengths in the page wikicode
+- Added `WikiPage::newSection()` and `WikiPage::setSection()` (shortcuts to `WikiPage::setText()`)
+- Added the ability to get individual sections of the article with `WikiPage::getSection()`
+- Added the ability to get all sections in an array with `WikiPage::getAllSections()`
+- Added the ability to get an array showing section offsets and lengths in the page wikicode
   with `WikiPage::getSectionOffsets()`
-* Added the ability to see how many sections are on a page with `WikiPage::getNumSections()`
+- Added the ability to see how many sections are on a page with `WikiPage::getNumSections()`
 
-### Version 0.3 - 2010-12-26
+## Version 0.3 - 2010-12-26
 
-* Initial commit
+- Initial commit
 
 [#25]: https://github.com/hamstar/Wikimate/pull/25
 [#28]: https://github.com/hamstar/Wikimate/pull/28
@@ -207,3 +210,4 @@ and may require changes in applications that invoke these methods:_
 [#134]: https://github.com/hamstar/Wikimate/pull/134
 [#135]: https://github.com/hamstar/Wikimate/pull/135
 [#136]: https://github.com/hamstar/Wikimate/pull/136
+[#138]: https://github.com/hamstar/Wikimate/pull/138

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contribution guidelines
 
-The Wikimate projects welcomes contributions of [all kinds](https://allcontributors.org/docs/en/emoji-key),
+The Wikimate project welcomes contributions of [all kinds](https://allcontributors.org/docs/en/emoji-key),
 no matter how small!
 Feel free to open [an issue](https://github.com/hamstar/Wikimate/issues/new)
 to discuss your suggestion or request,
@@ -27,4 +27,5 @@ Below are some guidelines that might help you prepare your contribution.
    When writing prose, break lines [semantically](https://rhodesmill.org/brandon/2012/one-sentence-per-line/).
    We don't have a strict maximum line length
    (especially since things like long URLs can easily surpass them),
-   but you should start thinking about breaking lines once they're approaching 100 characters in length.
+   but you should start thinking about breaking lines
+   once they're approaching 100 characters in length.

GOVERNANCE.md

@@ -1,6 +1,12 @@
+# Governance
+
+This page contains guidelines for current and prospective maintainers.
+
+## Process transparency and contributor onboarding
+
 The Wikimate project strives for a transparent and welcoming maintenance process.
-Below are some guidelines for current and prospective maintainers.
-Anyone is welcome to propose changes to this document via issues or pull requests.
+Discussions are expected to happen in public channels, via issues or pull requests,
+including proposals to change this document or the [contribution guidelines](CONTRIBUTING.md).
 
 Regular contributors are to be given collaborator status
 (which includes commit access, the ability to merge PRs, make releases, etc.).
@@ -37,14 +43,14 @@ It should apply the following actions:
    to the appropriate version name and date (e.g. "Version 1.2.3 - 2020-12-31")
    and add a new "Upcoming version" section heading above it,
    with the contents "No changes yet.";
-2. Edit the README and replace all references
+2. Edit `README.md` and replace all references
    to the previous version number and release date
    with the corresponding data for the new version;
 3. Update all version references in `Wikimate.php`
    to the new version.
 
-Once this PR is merged, create a new release 
-in https://github.com/hamstar/Wikimate/releases/new
+Once this PR is merged, create a new release
+in <https://github.com/hamstar/Wikimate/releases/new>
 (collaborator status is required for this step).
 
 The version tag and the title of the release notes should be in the format `v1.2.3`
@@ -55,5 +61,7 @@ of the relevant section in `CHANGELOG.md`.
 
 Finally, update the Wikimate entry on [Packagist](https://packagist.org/packages/hamstar/wikimate)
 (via the "Update Now" link in the right sidebar)
-and the corresponding row in the [PHP libraries table](https://www.mediawiki.org/wiki/API:Client_code/All#PHP) on MediaWiki.org,
-along with Wikipedia's [PHP bot framework table](https://en.wikipedia.org/wiki/Wikipedia:PHP_bot_framework_table) if applicable.
+and the corresponding row in MediaWiki.org's
+[PHP libraries table](https://www.mediawiki.org/wiki/API:Client_code/All#PHP).
+If applicable, also update Wikipedia's
+[PHP bot frameworks table](https://en.wikipedia.org/wiki/Wikipedia:PHP_bot_framework_table).

LICENSE.md

@@ -1,4 +1,4 @@
-## MIT License
+# MIT License
 
 Copyright (c) 2010-2021 Robert McLeod, Frans P. de Vries, and
 [contributors](https://github.com/hamstar/Wikimate/graphs/contributors)

README.md

@@ -1,11 +1,13 @@
+# Wikimate
+
 Wikimate is a PHP wrapper for the
 [MediaWiki Action API](https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page)
 that aims to be very easy to use.
 It currently consists of three classes:
 
-* **Wikimate** – Serves as a loader and manager for different wiki objects (e.g. pages).
-* **WikiPage** – Provides an interface to getting/editing pages or sections of them.
-* **WikiFile** – Provides an interface to downloading/uploading files and getting their properties.
+- **Wikimate** – Serves as a loader and manager for different wiki objects (e.g. pages).
+- **WikiPage** – Provides an interface to getting/editing pages or sections of them.
+- **WikiFile** – Provides an interface to downloading/uploading files and getting their properties.
 
 The [latest released version](https://github.com/hamstar/Wikimate/releases) of Wikimate
 is v0.15.0, released on Aug 26, 2021.
@@ -29,7 +31,9 @@ Then, download Wikimate, and initialise it by running `composer install`
 To use Wikimate within another project, you can add it as a composer dependency
 by adding the following to your `composer.json` file:
 
-    "hamstar/Wikimate": "0.15.0"
+```json
+"hamstar/Wikimate": "0.15.0"
+```
 
 ## Usage