bookdown / bookdown.bookdown Goto Github PK

View Code? Open in Web Editor NEW

81.0 10.0 11.0 717 KB

Core libraries for Bookdown generation.

Home Page: http://bookdown.io

License: MIT License

PHP 100.00%

bookdown.bookdown's Introduction

Bookdown

Bookdown generates DocBook-like HTML output using Markdown and JSON files instead of XML.

Bookdown is especially well-suited for publishing project documentation to GitHub Pages.

Read more about it at http://bookdown.io.

Current Work

tobiju/bookdown-bootswatch-templates is now part of Bookdown. You can use it by setting the "template": "bookdown/themes", in your bookdown.json

Templates

This is a list of custom bookdown.io templates

bdudelsack/bookdown-template

Tests

To run the tests after composer install, issue ./vendor/bin/phpunit at the package root.

Todo

(In no particular order.)

new bookdown.json elements
- "numbering": indicates how to number the pages at this level (decimal, upper-alpha, lower-alpha, upper-roman, lower-roman)
- "authors": name, note, email, and website of book authors
- "editors": name, note, email, and website of book editors
- "beforeToc": indicates a Markdown file to place on the index page before the TOC
- "afterToc": indicates a Markdown file to place on the index page after the TOC
- "subtitle": indicates a subtitle on an index page
navigational elements
- sidebar of siblings at the current level
- breadcrumb-trail of parents leading to the current page
features
- Automatically add a "date/time generated" value to the root config object and display on the root page
- Display authors, editors, etc. on root page
- A command to take a PHPDocumentor structure.xml file and convert it to a Bookdown origin structure (Markdown files + bookdown.json files)
- A process to rewrite links on generated pages (this is for books collected from multiple different sources, and for changing origin *.md links to target *.html links)
- Pre-process and post-process behavior to copy and/or remove site files
- Treat the root page as different from other indexes, allow it to be a nice "front page" for sites

bookdown.bookdown's People

Contributors

Stargazers

Watchers

Forkers

marquisknox diego-brocanelli bfolliot sandrokeil nasko tobiju bdudelsack llaville prolic harikt ahmedalbanna

bookdown.bookdown's Issues

Add note about rootPath to docs

Per #15

Table and Figure caption not showing Bengali characters

I am testing the bookdown-demo-master to see if a Bengali books can be written with bookdown. One issue I see is the caption of Fables and Figures. Non-English characters do not show up in the produced html file.

{r nice-tab, tidy=FALSE}
knitr::kable(
  head(iris, 20), caption = 'The বাংলায় ক্যাপশন হচ্ছে কিনা পরীক্ষা করছি!',
  booktabs = TRUE
)

When I run this, the output only shows "The !" in the caption of the table. That is it ignores the Bengali text completely. This is happening with Figure captions as well. Is there anything that I need to change to fix this? Thank you.

Add to staticgen.com

I was messing around with static generation stuff, and ran across this:
http://www.staticgen.com/

I was about to add bookdown, but I thought I'd ask first before randomly promoting your project on some random site.

Any reason I shouldn't?

Rendering Bash file scripts

This is with respect to issue opened at thephpleague/commonmark#173 .

So far it seems the issue with DomDocument . The comments are true I believe http://php.net/manual/en/class.domdocument.php#96709

PHP 7.2 count issue

There is a small bug with PHP 7.2 PHP Warning: count(): Parameter must be an array or an object that implements Countable in src/Content/TocHeading.php on line 47

Support for HTML base path

I've a problem with directories in the URL. The generated HTML link is absolute beginning with a /. Is it possible to add a bookdown.json config entry called base-path which writes in the HTML header the base path entry or is there a other solution?

<html>
  <head>
    <base href="http://sandrokeil.github.io/interop-config/">
  </head>
</html>

Here is the example page.

Help :: Issue with numbering

Hi Paul,

I was looking at the aura docs version 2.x, but it shows different number like below .

ie a bit confusing when we are going through the 2.x docs but showing 4 ...

Eg : http://auraphp.com/packages/2.x/Router.html#4-10

Is there a way we can turn off the numbering ?

Is there a 1.0.0-beta2 already planned ?

Hello,

I want to known, if there is a beta2 planned to be release.

I've, another time fell in that trap again. See my contrib about image not available #50

Thanks in advance

TocDepth not working properly?

@sandrokeil When I set "tocDepth": 1, at the root level, then I correctly see only one level of TOC depth at the root.

However, when I set it to 2 at the root level, I see all levels of TOC depth at the root.

This is in the bookdown.github.io develop branch.

I looked for, but did not see, a test for the tocDepth stuff, so that may be needed.

Thoughts?

International characters not rendered correctly

I'm having issues with Cyrillic characters.

This is my content file overview.md:

# Zend Framework 2

![ZF 2 Logo](images/zf2-elephant.png)

## План

* Въведение
* MVC
* Конфигурация
* ServiceManager
* PluginManager
* EventManager
* Модули
* Маршрутизация

I can verify that the file is saved with the proper encoding like this:

$ file _bookdown/zend-framework-2/overview.md 
_bookdown/zend-framework-2/overview.md: UTF-8 Unicode text

When I render the html, I can see that Cyrillic characters used in headings are rendered as non-printable gibberish, while Cyrillic characters used in the page content, are rendered as html entities:

Contents of rendered index.html:

<!-- snip -->

<h1>Zend Framework 2</h1>
<dl>
<dt>1. <a href="./overview.html#1">Zend Framework 2</a></dt>
<dd><dl>
<dt>1.1. <a href="./overview.html#1.1">Ð�Ð»Ð°Ð½</a></dt>
</dl></dd>
<dt>2. <a href="./intro.html#2">Ð�Ñ�Ð²ÐµÐ´ÐµÐ½Ð¸Ðµ</a></dt>
<dd><dl>
<dt>2.1. <a href="./intro.html#2.1">Ð�Ð¾Ð²Ð° Ð°Ñ�Ñ�Ð¸Ñ�ÐµÐºÑ�Ñ�Ñ�Ð°</a></dt>
<dt>2.2. <a href="./intro.html#2.2">Ð¡Ñ�Ð²Ð¼ÐµÑ�Ñ�Ð¸Ð¼ Ñ� PSR-2</a></dt>
</dl></dd>
</dl>

<!-- snip -->

This is how the actual content page is rendered in overview.html:

<!-- snip -->
<h1 id="1">1. Zend Framework 2</h1>
<p><img src="images/zf2-elephant.png" alt="ZF 2 Logo"></p>
<h2 id="1.1">1.1. &ETH;&#159;&ETH;&raquo;&ETH;&deg;&ETH;&frac12;</h2>
<ul>
<li>&ETH;&#146;&Ntilde;&#138;&ETH;&sup2;&ETH;&micro;&ETH;&acute;&ETH;&micro;&ETH;&frac12;&ETH;&cedil;&ETH;&micro;_</li>
<li>MVC</li>
<li>&ETH;&#154;&ETH;&frac34;&ETH;&frac12;&Ntilde;&#132;&ETH;&cedil;&ETH;&sup3;&Ntilde;&#131;&Ntilde;&#128;&ETH;&deg;&Ntilde;&#134;&ETH;&cedil;&Ntilde;&#143;_</li>
<li>ServiceManager</li>
<li>PluginManager</li>
<li>EventManager</li>
<li>&ETH;&#156;&ETH;&frac34;&ETH;&acute;&Ntilde;&#131;&ETH;&raquo;&ETH;&cedil;_</li>
<li>&ETH;&#156;&ETH;&deg;&Ntilde;&#128;&Ntilde;&#136;&Ntilde;&#128;&Ntilde;&#131;&Ntilde;&#130;&ETH;&cedil;&ETH;&middot;&ETH;&deg;&Ntilde;&#134;&ETH;&cedil;&Ntilde;&#143;_</li>
</ul>

<!-- snip -->

I'm attaching the sources folder: _bookdown and the rendered target folder: zend-framework-2 compressed as ZIP archives.

Might be, I'm not using the tool properly, in which case I'd be quite thankful for any advise you might offer!

_bookdown.zip
zend-framework-2.zip

Building new site throws Fatal Errors

I was just trying to create a new bookdown project and followed the instructions from Getting Started.

There has been no customization. The book folder is the same as Bookdown.Project.

I'm running PHP 7.0.6 on OSX.

The issue seems to be that in IndexProcess::processHtml when it's matching the header tags from $domDocument to the return value from $page->getHeadings() the first header element is the h3 from navheader.html but that is not a heading returned from $page->getHeadings().

If I change the h3 in navheader.html to a span tag, the site compiles correctly.

This is the output I get when I run bookdown.

$ ./vendor/bin/bookdown book/bookdown.json
Collecting content from book/bookdown.json
  Added root page from book/bookdown.json
  Added page book/example.md
Processing content.
  Applying Bookdown\Bookdown\Process\Conversion\ConversionProcess
    No origin for book/../../index.html
    Saving target book/../../index.html
    Reading origin book/example.md
    Saving target book/../../example.html
  Applying Bookdown\Bookdown\Process\Info\CopyrightProcess
  Applying Bookdown\Bookdown\Process\Headings\HeadingsProcess
    Processing headings for book/../../index.html
    Processing headings for book/../../example.html
  Applying Bookdown\Bookdown\Process\Resource\CopyImageProcess
    Processing copy images for book/../../index.html
    Processing copy images for book/../../example.html
  Applying Bookdown\Bookdown\Process\Toc\TocProcess
    Adding TOC entries for book/../../index.html
    Skipping TOC entries for non-index book/../../example.html
  Applying Bookdown\Bookdown\Process\Rendering\RenderingProcess
    Rendering book/../../index.html
    Rendering book/../../example.html
  Applying Bookdown\Bookdown\Process\Index\IndexProcess
    Create search index for book/../../index.html
    Create search index for book/../../example.html
PHP Notice:  Undefined offset: 3 in /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Process/Index/IndexProcess.php on line 115
PHP Stack trace:
PHP   1. {main}() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/bin/bookdown:0
PHP   2. Bookdown\Bookdown\Command->__invoke() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/bin/bookdown:28
PHP   3. Bookdown\Bookdown\Service\Service->__invoke() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Command.php:29
PHP   4. Bookdown\Bookdown\Service\Processor->__invoke() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Service/Service.php:25
PHP   5. Bookdown\Bookdown\Process\Index\IndexProcess->__invoke() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Service/Processor.php:27
PHP   6. Bookdown\Bookdown\Process\Index\IndexProcess->writeIndex() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Process/Index/IndexProcess.php:66
PHP   7. Bookdown\Bookdown\Process\Index\IndexProcess->processHtml() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Process/Index/IndexProcess.php:88

Notice: Undefined offset: 3 in /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Process/Index/IndexProcess.php on line 115

Call Stack:
    0.0002     357840   1. {main}() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/bin/bookdown:0
    0.0045     788704   2. Bookdown\Bookdown\Command->__invoke() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/bin/bookdown:28
    0.0047     797224   3. Bookdown\Bookdown\Service\Service->__invoke() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Command.php:29
    0.0127    1565600   4. Bookdown\Bookdown\Service\Processor->__invoke() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Service/Service.php:25
    0.0357    2316920   5. Bookdown\Bookdown\Process\Index\IndexProcess->__invoke() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Service/Processor.php:27
    0.0358    2316968   6. Bookdown\Bookdown\Process\Index\IndexProcess->writeIndex() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Process/Index/IndexProcess.php:66
    0.0359    2319528   7. Bookdown\Bookdown\Process\Index\IndexProcess->processHtml() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Process/Index/IndexProcess.php:88

PHP Fatal error:  Uncaught Error: Call to a member function getHref() on null in /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Process/Index/IndexProcess.php:119
Stack trace:
#0 /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Process/Index/IndexProcess.php(88): Bookdown\Bookdown\Process\Index\IndexProcess->processHtml('<html>\n  \n<head...', Object(Bookdown\Bookdown\Content\Page))
#1 /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Process/Index/IndexProcess.php(66): Bookdown\Bookdown\Process\Index\IndexProcess->writeIndex(Object(Bookdown\Bookdown\Content\Page), 'book/../../inde...')
#2 /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Service/Processor.php(27): Bookdown\Bookdown\Process\Index\IndexProcess->__invoke(Object(Bookdown\Bookdown\Content\Page))
#3 /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Service/Service.php(25): Bookdown\Bookdown\Service\Processor->__invoke(Object(Bookdown\Bookdown\Content\RootPage))
#4 /pr in /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Process/Index/IndexProcess.php on line 119

Fatal error: Uncaught Error: Call to a member function getHref() on null in /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Process/Index/IndexProcess.php on line 119

Error: Call to a member function getHref() on null in /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Process/Index/IndexProcess.php on line 119

Call Stack:
    0.0002     357840   1. {main}() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/bin/bookdown:0
    0.0045     788704   2. Bookdown\Bookdown\Command->__invoke() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/bin/bookdown:28
    0.0047     797224   3. Bookdown\Bookdown\Service\Service->__invoke() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Command.php:29
    0.0127    1565600   4. Bookdown\Bookdown\Service\Processor->__invoke() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Service/Service.php:25
    0.0357    2316920   5. Bookdown\Bookdown\Process\Index\IndexProcess->__invoke() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Service/Processor.php:27
    0.0358    2316968   6. Bookdown\Bookdown\Process\Index\IndexProcess->writeIndex() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Process/Index/IndexProcess.php:66
    0.0359    2319528   7. Bookdown\Bookdown\Process\Index\IndexProcess->processHtml() /private/var/www/BookdownTest/_bookdown/vendor/bookdown/bookdown/src/Process/Index/IndexProcess.php:88

Option to insert Disqus

Is there a plan to allow for inserting Disqus section to HTML pages? A particular user case that motivates the request is to create via bookdown a lab notebook to organize daily research, where analysis procedures are published allowing for random comments be made by colleagues on the same page under the Disqus section.

Thank you!

Move minimum PHP version to 5.6?

@sandrokeil @tobiju et al -- do we care very much if the next release has a minimum PHP version of PHP 5.6, to soothe some of the dependency packages' latest versions?

TOC depth limit status

How is the status of the TOC depth limit? There exists a branch but it's currently not implemented or?

How to add sidebar of siblings at the current level?

This can be achieved with plain PHP or is there another approach?

$sidebarEntries = $page->getHeadings();

Content order in bookdown.json

It seems that structure of bookdown.json is little bit broken. The order of content items may be unspecified, when it's read by something other than php.

To cite specification:

An object is an unordered set of name/value pairs.

Warning produced

Warning: count(): Parameter must be an array or an object that implements Countable in /vendor/bookdown/bookdown/src/Content/TocHeading.php on line 47

How to add content search like lunr.js?

I would like to implement a documentation search mechanism like lunr.js. Lunr is base on a json file which holds the index. I think we can implement an json processor to generate the index for every book. Frontend stuff could be implemented in tobiju/bookdown-bootswatch-templates. Do you have any suggestions to that?

Q: template value

Is is possible to define a template value where a token is replaced in renders?

eg.

variable

$SERVER_URI = 'example.com';

template:

Our server is available at http://{$SERVER_URI}/some/path

renders as:

<p>Our server is available at http://example.com/some/path</p>

Architectural overview

I am planning to implement EPUB output for Bookdown.

I need to decide which classes to reuse and which to rewrite.

Can you provide some architectural overview to make my decisions easier?

Command-line flags

We're planning on using Bookdown for the documentation of the various Zend Framework components. One thing I'd like to be able to do is have a bare-minimum bookdown.json that specifies the title and content, and optionally the default target, and then specify the template (and possibly the target) via a command-line flag. This would allow us to have the "official" templates in a top-level repo that aggregates documentation from each of the components, but also allow developers to render the documentation using that template if it's checked out somewhere on their filesystem:

$ bookdown --template=../documentation/templates/main.php doc/bookdown.json

Or, to override the target:

$ bookdown \
> --template=../documentation/templates/main.php \
> --target=../documentation/html/ \
> doc/bookdown.json

Releases needed

Hi Paul,

It looks we need releases for the bookdown.

I was trying to update the aura docs and bookdown throws some exceptions. I manually fixed it and was looking to send a PR noticed this is already fixed, but not released.

If possible please tag.

Thank you.

How to implement breadcrumbs?

The breadcrumb trail can be implemented in the template with plain PHP or is there another approach?

$page = $this->page;
$breadcrumb = [];

while ($page) {
    $breadcrumb[] = $page->getTitle();

    $page = $page->getParent();
}

echo implode(' -> ', array_reverse($breadcrumb));

How to add the custom root page feature?

@pmjones I want to add the custom root page feature. What is the best way?

Simply allow index as content page and if set, create a toc.html file
Add a new bookdown.json entry rootPage and use it as index.html and create a toc.html file

Any option to disable rendering of heading numbers?

Sorry for submitting an issue for this, but I couldn't think of any other way to ask - is there any way to configure the headings to not be rendered with their respective numbers?

I browsed the default templates and figured that by using my own version of toc.php I could render the TOC entries without numbers, but what about the inline headings - those rendered in the page content?