What techno do you use to generate the documentation ?

[MatthieuL]

Hi !

I really like the way you handle documentation using markdown pages (https://github.com/raspberrypi/documentation/) which are then nicely displayed on the main website:
https://www.raspberrypi.org/documentation/

On our project, we also have markdown documentation hosted on github but we do not have the nice HTML/CSS template you have to render static documentation pages.

So I would like to know more about the techno your are using ?

Thanks !

Matthieu

[MatthieuL]

So I continue looking for hints in the source code about the way you do.

It seems there is a wordpress somewhere and the few ruby code on the repository transform markdown syntax into HTML one.

I just need to find the black matter which link the 2...

[panik]

Have a look at Parsedown: http://parsedown.org/

Code: Select all

<?php
include("Parsedown.php");

$markdown = file_get_contents('path/to/file.md');
$markup = Parsedown::instance()->text($markdown);
echo $markup;
?>

The css could be anything from anywhere that styles basic html.

[MatthieuL]

Thanks for the link, I did not know this tool.

Yet I'm not sure this is used on the raspberry pi documentation, or I do not undestand why there is a gemfile and a rakefile on the github repo.
It seems there is something build on the github server (travis config) then something get the HTML and display it with a template on the main website.

[panik]

It'd be interesting to know what those files are about. They possibly have something to do with automatically updating the website after a commit/push. Not sure.

I'm using a simple bash script to wget the raw .md files from github to an offline directory, renaming them appropriately and then ftp it to the live website. My workflow is:

Code: Select all

git push origin master
./updatewebsite.sh

Lo-tech, but efficient.

Obviously, ftp straight from the source directory works too, but I'm too lazy for that. Too many files and names to remember.

[ghans]

Travis is instructed to use the Rakefile to render and test the Markdown. The renderer is redcarpet.
How the result gets onto the official website is a mystery to me too.

ghans

[ben_nuttall]

Yet I'm not sure this is used on the raspberry pi documentation

I can confirm it does use Parsedown.

I have an .htaccess file that redirects all requests into index.php, which looks up the request inside the docs folder (a clone of the repo), and renders it in a template to make it look like the rest of the website.

The learning resources work in the same way, but with a much more bespoke template. Depending on the request, either a cover page, requirements page, worksheet, etc. is rendered. These templates pull in bits of other files, and use YAML files for other config.

I wrote about the non-technical side of this - why we do it, etc, at opensource.com

or I do not undestand why there is a gemfile and a rakefile on the github repo.
It seems there is something build on the github server (travis config) then something get the HTML and display it with a template on the main website.

The Travis CI stuff is nothing to do with the markdown->HTML parsing. It's just a continuous integration build that tests the markdown is ok, no broken links, etc.

[ghans]

Thanks for the followup . The articles at opensource.com are interesting too.

ghans

[MatthieuL]

I have an .htaccess file that redirects all requests into index.php, which looks up the request inside the docs folder (a clone of the repo), and renders it in a template to make it look like the rest of the website.

Thanks ben, it is more clear now.
However, for a non-web-dev like me, it seems there is a lot of step before making all this work correctly.

Does your website is somehow "open", i.e. can you share the code you have so we can see how it is actually done ?

- the htaccess redierctions
- index.php
- the template

[DougieLawson]

I can confirm it does use Parsedown.
[snip]
I wrote about the non-technical side of this - why we do it, etc, at opensource.com

That's for sharing that. And thanks to panik for the link to "Parsedown", I've snagged a copy of that as being able to test my markdown before I publish it on Github has lots of value.

[panik]

That's for sharing that. And thanks to panik for the link to "Parsedown", I've snagged a copy of that as being able to test my markdown before I publish it on Github has lots of value.

It might be noteworthy that github uses a 'github flavored markdown' which Parsedown renders correctly.
https://help.github.com/articles/github ... -markdown/

[mc007ibi]

I am using markdown with daux.io, it takes a directory filled with markdown files and then creates a boostrap3 based
page, it creates offline docs too. there are others too...