Re: MarkDown conversion of specification live on SPDX GitHub

Thomas Steenbergen



Sorry did not find the time to reply to this thread earlier…


@all: Got asked this a couple times – Why Gitbook and not an alternative like Pandoc? My choice in GitBook was driven since I wanted to reduce the threshold for contributions. GitBook offered a defined format + structure, nice HTML output and a nice all-in-one solution including a WYSIWYG editor with GitHub upload (limited Git knowledge required). Could build this with PanDoc as well, have done so before but would have been more work and harder for others to maintain.


@Matjia: I should have been clearer in the limitation wording. Should have change “Simplified lay-out as MarkDown” to “Simplified lay-out as MarkDown and GitBook“

ToC simplification is because GitBook by default does not allow anchors in its ToC. I have tested several of the ToC plugins you link to but ones I tried either only worked in HTML or had issues. Will complete testing ToC plugins and ten pick one.


As part of fixing broken links I also inserting HTML anchors in MarkDown, hope I find the time to finish this change with next few days and push it to GitHub. My plan is to submit some pull requests to GitBook 4.x to fix some of the limitations I found.


@Jack @Trevor: Yes, it’s possible to build multiple versions on the gh-pages branch but uncommon way of working and think this may confuse users.  Topic was discussed in yesterday’s technical meeting current agreement was to have official releases on I am thinking to extend current Gulp build script with 2 new tasks 1) a task to automate deployment of an official release to 2) a task to deploy any new release tag to GitHub Releases




Thomas Steenbergen

Principal Engineer Open Source Governance and Policy


HERE Deutschland GmbH, Place of Business: Invalidenstraße 116, 10115 Berlin, Germany – Commercial Register: Amtsgericht Charlottenburg, HRB 106443B - USt-IdNr.: DE 812 845 193 - Managing Directors: Michael Bültmann, Robertus A.J. Houben


From: <spdx-bounces@...> on behalf of Brad Edmondson <brad.edmondson@...>
Reply-To: "brad.edmondson@..." <brad.edmondson@...>
Date: Monday 10 July 2017 at 22:54
To: "W. Trevor King" <wking@...>
Cc: "opensource@..." <opensource@...>, "spdx@..." <spdx@...>
Subject: Re: MarkDown conversion of specification live on SPDX GitHub


+1 for continuous build (I think that's what gulp is), and it gives you linkable tags for free. Very nice.


Brad Edmondson, Esq.
512-673-8782 | brad.edmondson@...


On Mon, Jul 10, 2017 at 1:41 PM, W. Trevor King <wking@...> wrote:

On Thu, Jul 06, 2017 at 02:38:24PM +0000, Manbeck, Jack via Spdx wrote:
> I want to link to the HTML spec from the website. Is it possible to
> label the 2.1 version so only that shows up on a link?

Once appoach to that would be having gulp build master and and all
tags (that have Markdown content), instead of just building master.
For example:

would be the master build,

would be a build of the 2.1.1-rc1 tag if/when that tag is made,

would be abuild of the 2.1.1 release if/when that tag is made, etc.
I'm happy to help with tooling for this if it sounds useful.


This email may be signed or encrypted with GnuPG (
For more information, see

Spdx mailing list


Join to automatically receive all group messages.