The Moodle Book github tool allows the import/export (pull/push) of Book content from/to GitHub. The content from the Moodle Book is stored as a single file on GitHub. One of the many unanswered questions about the tool is the format of the exported file. The current format is a bit of dodgy HTML with divs, classes, and ids. Aim here is to figure out if and how the HTML 5 semantic elements might provide a more useful method.
Given that my last serious web development role and interest was 10+ years ago, some of the following is likely to be a bit silly. It’s not helped by the fact that the online explanation of some of these elements differ and the whole semantic element thing appears to be somewhat less than widely supported and used.
HTML 5 semantic elements
Are a collection of elements/tags in HTML 5, including <article> <aside> <header> etc that are intended to help define different parts of a web page and thus make it easier to share/reuse data across applications. Sounding exactly like what is needed here.
All are probably relevant, but the more immediately relevant include:
- <article> – Specifies independent, self-contained content.
Good match for an individual book. Includes sections. - <section> – A section in a document.
Good match for a book chapter (or sub-chapter)? Can be nested. - <header> – for either a document or section
Could be used within a section to specify the title of the chapter from the book, but also appear on the page when viewing the single file. - <footer> – for either document or section
Could be used within a section to hold icons for next/previous (getting optional here) - <nav> – defines a set of navigation links
Thinking this could be added to the github file by the tool to add navigation links within the file. Ability to jump to specific chapters etc. - <aside>
- <details>
- <main>
Structure for the single github file
Which brings me to to the following. Note: the Moodle book calls every page a chapter or a sub-chapter. A sub-chapter(s) is nested within a chapter.
[code lang=”html”]
<html>
<header>
<title>Title of book in Moodle</title>
</header>
<body>
<article data-title="Title of book in Moodle" data-introformat="1" data-customtitles="0" data-numbering="1" data-navstyle="1">
<header>
<h1>Title of book in Moodle</h1>
<div>Introduction to the book from Moodle</div>
</header>
<section data-pagenum="1" data-contentformat="1" data-title="Title of 1st chapter from book">
<header>
<h1>Title of 1st chapter from book</h1>
</header>
CONTENT OF THE CHAPTER from the book
<section data-pagenum="2" data-contentformat="1" data-title="Title of 2nd chapter (and a sub-chapter) from book">
<header>
<h1>Title of 2nd chapter (and a sub-chapter) from book</h1>
</header>
Content of the sub-chapter from the book
</section>
</section>
<section data-pagenum="2" data-contentformat="1" data-title="Title of 3rd chapter from book">
<header>
<h1>Title of 3rd chapter from book</h1>
</header>
CONTENT OF THE 3rd CHAPTER from the book
</section>
</article>
</body>
</html>
[/code]
Entering HTML like that to get pretty coloured in WordPress is harder than it looks.
Testing the structure is quite easy given this online outliner.
Questions
My first question is whether or not the above is “valid” HTML 5? The outliner seemed to like it.
The second question is whether or not the above will work? Not from a HTML 5 perspective, but my code.
Which picks up the following questions
- Do the data attributes play nicely with semantic elements?
- Should the title be both a data attribute and in the header element?
- Should I rely on the parsing code to auto-generate pagenum?
- Should I rely on the parsing code to identify chapters and sub-chapters?
- Are there any nice existing javascript resources that will auto-generate the navigation between chapters? (Or do I have to write something?)
- Are there any nice CSS resources that will style semantic elements nicely? (Or do I have to write something?)
- Will the PHP parsing code handle semantic elements (and data attributes)?
