Markdown wiki sync with Github

image data/images/lab/2015-11-04_wiki-A2.jpg
I received many email, comments and feedbacks about the need of a central Wiki for the universe of Pepper&Carrot named Hereva. That's why I decided to add a collaborative Wiki to the website. You can find it on the top categorie. That's the start of a new adventure, and I hope I'll use it to add more details, and illustrate it step by step. Corrections and proof-reading needed :)

Technical details:


The wiki is manually sync with the Github wiki . Github wiki is a git repository with markdown files.  Here is a screenshot of the folder with the markdown files.



It's easy to clone or to edit online with a Github account.
git clone https://github.com/Deevad/peppercarrot.wiki.git

To translate the markdown files to Html, I used an open library named parsedown.php. I used the static pages of Pluxml ( the CMS I use for running Pepper&Carrot ) to display the markdown pages. I also generated a menu with PHP to wrap-up everything. A Wiki is born!

PHP code for Pluxml


Here is my PHP code to include a markdown page inside a Pluxml static page ( static8/wiki in my case ), I share it because I didn't found anything like this on internet, and I had to do it from scratch. I guess a lot of project would like to have this type of sync between website and a markdown wiki and this code should be pretty standard and easy to tweak because I fully commented it :

Loading the Markdown pages :
<?php

// get variable 'page' from URL
$wikipage = htmlspecialchars($_GET["page"]);

// Security, remove all special characters except A-Z, a-z, 0-9, dots, hyphens, underscore before interpreting something.
$wikipage = preg_replace('/[^A-Za-z0-9\._-]/', '', $wikipage);

if(isset($_GET['page']))
{
// page found
}else{
// no page found, we propose fallback homepage Home.md
$wikipage = "Home";
}

// add library to parse markdown Github files
include(parsedown.php');

// display content main page
$contents = file_get_contents('path/to/your/folder/'. $wikipage .'.md');
$Parsedown = new Parsedown();
echo $Parsedown->text($contents);
?>

Generating the Menu buttons :
<?php
// dynamic menu generation from a folder

# we scan all markdown in folder
$search = glob("path/to/your/folder/*.md");

# we loop on found files
if (!empty($search)){
foreach ($search as $wikifile) {

// clean path to filename only
$wikifile = basename($wikifile);

// _Footer and _Sidebar are special page, they start with '_' exclude them
if (substr($wikifile, 0, 1) === '_') {
// page starting with '_' found, do nothing.
} else {
// Check if the page is Home, we don't display it here to keep it hardcoded on the top
if ($wikifile === 'Home.md') {
// Home.md found, do nothing
} else {
// Finally! we have a valid markdown page
// Clean filename to get only name without extension :
$wikifile = preg_replace('/\\.[^.\\s]{2,4}$/', '', $wikifile);
// Is there a chance we display the page of this button now? time to set status actif!
if ($wikifile === $wikipage) {
}
// Ok, we have all, diplay this button now :
echo '<a class="button" href="https://www.peppercarrot.com/';
$plxShow->urlRewrite('?static8/wiki&page='.$wikifile);
echo '" title="">'.$wikifile.'</a>';
}
}
}
}
?>
I hope it will be useful and you'll enjoy the Wiki !

5 comments

link   libre fan   , - Reply

Bravo pour cette idée de Wiki!

Mais est-ce que ce genre de synch serait possible avec une plateforme libre telle https://git.framasoft.org/(fourni par Framasoft) ou par Riseup.net https://labs.riseup.net

Ou est-ce que github est irremplaçable? (un jour, je pense, ce sera à peu près aussi intolérable que Sourceforge).

link   David REVOY   Author , - Reply

@libre fan : Merci! Github est remplaçable, bien sur :) Je garde en local un clone avec toutes les révisions 'Git' et ce serait facile de changer ou d' héberger vers un autre service. L'avantage de Github est dans son audience: beaucoup de collaborateurs y ont déjà un compte et cela leur facilite les contributions. Allez vers un autre service créerai une distance, voir un mur envers cette facilité. En effet, les autres systèmes de portails Git demandent souvent des choses compliqués ; des clefs SSH, des authentification, tout un protocole de sécurité poussé avant de pouvoir faire une simple contribution. Je vais étudier GitLab et FramaGit. Surtout si il propose le même type de confort social et une facilité d'inscription/participation.

link   libre fan   , - Reply

Merci de tes explications.
Ce qui est très déplaisant dans Github, c'est qu'ils mettent pas mal de projets sur le cloud d'amazon et autres cdn qui récoltent ainsi des «clients» involontaires. C'est irritant d'être de la chair à data en allant télécharger une extension (uMatrix, par ex sur Github) pour éviter justement l'espionnage de ces entreprises…

En regardant vaguement la page d'aide https://git.framasoft.org/help
je n'ai pas l'impression que le SSH soit obligatoire, et il semble que les permissions variées pour les utilisateurs permettent des contributions simples.

Je n'ai pas essayé de m'enregistrer mais ça n'a pas l'air compliqué (nom, pseudo, mail).
Comme tu dis, il faut que tu regardes tout ça d'abord. Moi, je n'y connais pas assez.

link   David REVOY   Author , - Reply

@libre fan : Hello, oui je comprends bien :) Je me suis inscrit cette semaine en contributeur dans un projet open-source utilisant leur propre Gitlab hébergé sur server. J'y apprends l'experience côté utilisateur et les possibilités. Jusque là, la structure est parfaite.

link   Jacques Duff   , - Reply

good work thanks for sharing

Leave a reply

Notice : URL allowed ( auto-clickable ). Pictures URL too ( gif,jpg,png auto-displayed )

Capcha

Enter image code