jeroen-de-dauw / mediawiki-github
Simple MediaWiki extension for embedding GitHub hosted content in wiki pages. Supports markdown rendering and syntax highlighting.
Fund package maintenance!
JeroenDeDauw
Installs: 220
Dependents: 0
Suggesters: 0
Security: 0
Stars: 26
Watchers: 6
Forks: 15
Open Issues: 10
Type:mediawiki-extension
Requires
- php: >=7.1
- ezyang/htmlpurifier: ~4.9
- jeroen/file-fetcher: ~6.0
- jeroen/file-fetcher-cache: ~1.0
- jeroen/simple-cache: ~2.0
- mediawiki/parser-hooks: ~1.5
- michelf/php-markdown: ~1.7
Replaces
README
If you need only markdown rendering, please use the External Content extension instead.
Simple MediaWiki extension for embedding content of files hosted in GitHub git repositories. It supports markdown rendering, syntax highlighting and caching.
Professional support and custom development is available via Professional.Wiki.
Requirements
Installation
The recommended way to install the GitHub extension is with Composer using MediaWiki 1.22 built-in support for Composer.
In your MediaWiki root directory, you can execute these two commands:
COMPOSER=composer.local.json composer require --no-update jeroen/mediawiki-github "~1.4"
composer update jeroen/mediawiki-github --no-dev -o
For more details on extension installation via Composer, see the documentation on MediaWiki.org.
Verify installation success
Go to Special:Version and see if GitHub is listed there. If it is, you successfully installed it!
Configuration
The default GitHub repo can be set using the $egGitHubDefaultRepo
setting. Assign to this setting
the name of the default repo in your LocalSettings file, after the inclusion of this extension e.g.
for Semantic MediaWiki as follows:
$egGitHubDefaultRepo = 'SemanticMediaWiki/SemanticMediaWiki';
To restrict from which repositories files can be fetched, use the egGitHubRepositoryWhitelist
setting. If this list is empty, which it is by default, users can fetch files from whatever
wiki they specify. This means they can include potentially harmful content. The extension should
escape harmful content; this setting adds an extra layer of security.
To allow only files from a single repo:
$egGitHubRepositoryWhitelist = [ 'SemanticMediaWiki/SemanticMediaWiki', ];
To allow files from multiple repos:
$egGitHubRepositoryWhitelist = [ 'SemanticMediaWiki/SemanticMediaWiki', 'JeroenDeDauw/GitHub', 'JeroenDeDauw/Maps', ];
Syntax highlighting
If you want code syntax highlighting you need to have the SyntaxHighlight extension enabled and configured.
Caching
The file contents gets cached in memory during the PHP request. The main MediaWiki cache
is used as secondary cache, with a default TTL of 600 seconds. You can use the
$egGitHubCacheTime
setting to change the TTL:
$egGitHubCacheTime = 900;
You can modify which caching method is used. The supported methods are
'full'
- use in memory and MediaWiki caches'none'
- do not do any caching
The default is 'full'
. You can change this setting as follows:
$egGitHubCache = 'none';
Network
You can modify the GitHub raw content URL used to fetch the files. The default is
https://rawcdn.githack.com
, due to https://raw.githubusercontent.com
not working on all systems.
You can change this setting as follows:
$egGitHubUrl = 'https://raw.githubusercontent.com';
You can modify which method is used to fetch the file. The supported methods are
'mediawiki'
- use MediaWikis HTTP class'simple'
- use PHPs file_get_contents
The default is 'mediawiki'
. You can change this setting as follows:
$egGitHubFetcher = 'simple';
Usage
Add {{#github:FileName}}
to your wiki page, where FileName is the name of the file you want to embed.
This can include a path, for instance {{#github:docs/INSTALL.md}}
.
You can also specify the repo name and the branch name: {{#github:FileName|user/repo|branchName}}
.
For syntax highlighting, this extension uses the same attributes as the SyntaxHighlight extension: lang, line, start, highlight, inline. Theses can be specified in any order using the attribute names.
{{#github:FileName|user/repo|branchName|lang=bash|line=1|start=1|highlight=1,5,4|inline=0}}
The lang
parameter can be specified as the fourth positional argument.
{{#github:FileName|user/repo|branchName|bash}}
The defaults are line=0, start=1, and inline=0 when this functionality is activated.
Release notes
1.6.0 (2020-02-21)
- Changed default GitHub raw content url to
https://rawcdn.githack.com
(thanks to @lmn8)
1.5.0 (2019-04-09)
- Changed minimum PHP version to 7.1
- Updated dependencies to increase compatibility
1.4.2 (2017-09-28)
- Fixed bug in the MediaWiki file fetching code and made it the default method again
1.4.1 (2017-07-01)
<pre>
HTML tags no longer get stripped out of the content
1.4.0 (2017-06-30)
- Changed extension installation location from vendor to the MediaWiki extensions folder
- Added
$egGitHubCache
setting, allowing for complete disabling of the cache - Added error logging of failed HTTP requests to GitHub
1.3.0 (2017-06-09)
- Dropped support for PHP < 7.0
- Added
egGitHubRepositoryWhitelist
setting - Made code more robust in failure cases
1.2.0 (2017-04-17)
- Added support for syntax highlighting using MediaWiki's included SyntaxHighlight extension (by Shay Harding)
1.1.1 (2016-11-06)
- Fixed critical issue caused by failing i18n registration on recent versions of MediaWiki
1.1.0 (2016-07-11)
- Dropped support for PHP < 5.5
- Fixed error on file not found. The parser function will now return an empty string in this case.
1.0.3 (2016-07-10)
- Fixed version number on Special:Version
- Switched from FileFetcher ~2.0 to ~3.1
1.0.2 (2015-01-20)
- Added
$egGitHubFetcher
setting - The files are now by default fetched using
file_get_contents
rather than MediaWikisHTTP
class
1.0.1 (2015-01-19)
- Dropped support for MediaWiki < 1.24
- Added
$egGitHubUrl
setting - Changed default GitHub raw content url from
https://raw.githubusercontent.com
tohttps://cdn.rawgit.com
(thanks to Mike Cariaso)
1.0.0 (2015-01-19)
New features
- Added support for markdown. Files ending on .md or .markdown are now rendered appropriately
- Added
$egGitHubCacheTime
setting
Compatibility changes
- The extension now needs to be installed via Composer
- The package name has changed from
jeroen-de-dauw/mediawiki-github
tojeroen/mediawiki-github
Enhancements
- Compatibility with the latest version of the GitHub API has been added
- PSR-4 based autoloading is now used
- The ParserHooks library is now used for the github parser hook
- Additional tests have been added
0.1.0 (2013-07-15)
- Initial release
Running the tests
To use MediaWiki vagrant, see this gist which includes the steps needed to install PHP7 and run the MediaWiki test runner with PHPUnit 6+.
To run code style checks and the tests that do not rely on MediaWiki, execute this in the base directory:
composer ci
Author
The GitHub extension was created and is maintained by Jeroen De Dauw.