project docbook {🖫 31, ⚐ 9, ★ 0}

atelierspierrot/docbook

Simple CMS PHP app to build rich HTML5 views from a Markdown contents filesystem.

Friday, January 16, 2015
by picas
Repository
0 Watchers
0 Stars
31 Installations

0 Dependents
0 Suggesters
0 Forks
0 Open issues
9 Versions
0 % Grown

The README.md

DocBook is a simple PHP app to build rich HTML5 views from Markdown files following a filesystem architecture. It embeds some classic CMS' website features like a search in contents, some RSS feeds generation or translations switching., _(*1)

DocBook builds a "like-a-book" interactive website from simple Markdown files., _(*2)

Features

DocBook is a simple application organized beyond a filesystem architecture of Markdown files. Each file is a "page" and each sub-directory is a "section" of pages. The title of the files or directories is used to be the title of the page or section., _(*3)

The views generated by DocBook are constructed in full HTML5 with the help of Bootstrap., _(*4)

Special files

Any file named INDEX.md in a directory will be considered as its index and be delivered if no other file is requested in the URL., _(*5)

Any file named README.md in a directory will be displayed at the bottom of the directory contents indexing, just like the default behavior of Apache., _(*6)

Files infos

For each file, a set of dependencies can be defined to overwrite the default values, that must themselves be defined at the project root directory. These files are, by default:, _(*7)

*.copyright.md: a copyright, license or protection information for the file content,
*.author(s).md: an information about the author(s) of the file,
*.changelog.md: the evolutions information of the file.

Markdown syntax

The Markdown syntax used by DocBook follows the Markdown Extended rules. They are inherited from:, _(*8)

the original John Gruber's syntax,
the "extra" version from Michel Fortin,
some features are also included from the Fletcher Penny's MultiMarkdown.

Translations

Each document can be translated, naming the translation file like:, _(*9)

CONTENT.md
CONTENT.fr.md // translation in French
...

URL routing

Globally or for each of your DocBook directories, the following routes are available:, _(*10)

*/sitemap: build a sitemap XML from this position and through its children,
*/notes: build a page referencing all footnotes from this position and through its children,
*/glossary: build a page referencing all glossary entries from this position and through its children,
*/bibliography: build a page referencing all bibliographic entries from this position and through its children,
*/rss: build an RSS feed of contents from this position and through its children,
*/search?s=A&ln=LN: process a search of string "A" in contents from this position and through its children in the specified language if defined.

For each file of your DocBook, the following routes are available:, _(*11)

*/ln?LN: get this content in LN language if present,
*/download: download the original file of the page,
*/htmlonly: get the plain HTML version of the page,
*/plain: get the plain text version of the page.

Data files organization

All your Markdown files, the real pages of your website, have to be stored in the www/ directory or its sub-directories., _(*12)

Any assets, image or other media file, that you want to include or use in your Markdown contents must be stored in an assets/ sub-directory in the current directory. If you do not follow this rule, your file will not be accessible by Apache., _(*13)

By default, any file contained in a directory named wip/ will not be displayed publicly and will not be referenced in the sitemap neither in the index ; to view it, you will have to manually write its URL (see the Routing section of this document to learn more about the application URLs' construction)., _(*14)

Knowing that, a classic DocBook directory organization should be:, _(*15)

| chapter-name/
| ------------- README.md           // the first file shown loading the directory
| ------------- assets/             // a directory containing your medias
| ------------- wip/                // a directory containing your work-in-progress contents
| ------------- PAGE.md             // a Markdown content file (page 1)
| ------------- OTHER-PAGE.md       // another Markdown content file (page 2)
| ------------- OTHER-PAGE.fr.md    // the french translation of page 2
| ------------- sub-chapter1/       // a sub-directory containing a sub-chapter
| ------------- sub-chapter2/       // a sub-directory containing another sub-chapter

The DocBook chapters

All your first depth directories (directories contained directly in your DocBook www/ root) are considered as your chapters and are listed in the header navigation bar of each page for quick access., _(*16)

Organization

For more informations about how to use DocBook every day, browse the /docbookdoc URL of your installation to read the DocBook user manual. A link to this manual is always accessible in the header navigation bar of each page., _(*17)

Architecture

The default global architecture of your DocBook is:, _(*18)

| src/
| tmp/
| user/
| www/

src/ contains the PHP sources of the application and the template files ; to define a new template, put your file here ; it must follow an architecture like:, _(*19)
```
| src/
| ---- config/
| ---- DocBook/
| ---- templates/
```
tmp/ is a sub-directory to store some configurations and cached files ; the best practice is to not touch them but you can, in extreme conditions, erase all its contents without worry ; it is (re-)generated by the application ;, _(*20)
user/ is the directory to put your own user configuration or templates (see the Fallback system section for more info) ; you can create it as it doesn't exist in the distribution ; it may follow an architecture like:, _(*21)
```
| user/
| ---- config/
| ---- templates/
```
www/ sub-directory must be the DOCUMENT_ROOT of your virtual host (anything outside this directory is not used in HTML pages) ; it must follow an architecture like:, _(*22)
```
| www/
| ---- docbook_assets/
| ---- .htaccess
| ---- index.php
```

NOTE - A vendor/ sub-directory will be created by the application in both src/ and www/docbook_assets/ directories to store the vendor external packages used by DocBook ; do not modify them., _(*23)

Fallback system

The application is constructed to allow user to over-write some configuration settings and the templates used to build the pages. This feature is quite simple:, _(*24)

by default, some configurations and templates are embedded with the application in the src/config/ and src/templates/ directories ;
any file found in the user/config/ will be taken primary to the default config and any file found in the user/templates/ will be taken primary to the default templates.

The templates follows a specific rule as the application can use a collection of templates to build different designs for pages., _(*25)

Custom templates

As this application uses Twig to build its views, if you want to write your own templates you may follow Twig's documentation., _(*26)

License / Dependencies

DocBook is an open-source application released under a GNU General Public License version 3. You can freely download it, use it or distribute it as long as you stay in the license conditions. See the License file for more info., _(*27)

DocBook is developed with the help of the following third-parties:, _(*28)