index.json

[{"id":"\/intro\/what-is-bookdown.html#1-1","title":"1.1. What Is Bookdown?","content":"Bookdown generates DocBook-like HTML output using CommonMark (a variation of Markdown) and JSON files instead of XML.Bookdown is especially well-suited for publishing project documentation to GitHub Pages.Features include: Automatic table-of-contents generation as index pages at each hierarchy level Custom index-page titles via JSON configuration Automatic numbering of page headings Automatic previous\/next\/up navigation headers and footers Multi-page hierarchical output Loading of remote content files via HTTP Templated output for theming Overridable page processing, especially for rendering Downloading of linked images CommonMark extension support Depth level of table of contents Setting a copyright hint Support for 3rd party templates Bookdown can be used as a static site generator, or as a way to publish static pages as a subdirectory in an existing site."},{"id":"\/intro\/getting-started.html#1-2-1","title":"1.2.1. Prerequisites","content":"Bookdown uses PHP. It runs on PHP 5.6 and later, but we recommend using the latest available version of PHP."},{"id":"\/intro\/getting-started.html#1-2-2","title":"1.2.2. Installation","content":"First, choose an existing project directory, likely a Git repository. We will call this the {$REPO} directory.Next, use Composer to install a Bookdown skeleton as a subdirectory inside {$REPO}. We suggest _bookdown\/ since Github Pages will not publish underscore-prefixed paths.cd {$REPO} composer create-project bookdown\/project _bookdown\/ You may wish to add the following lines to {$REPO}\/.gitignore so that the underlying libraries are not committed to your main repository.\/_bookdown\/vendor "},{"id":"\/intro\/getting-started.html#1-2-3","title":"1.2.3. Confirming Installation","content":"The Bookdown skeleton includes an example to confirm that installation succeeded. Change into the skeleton directory, then issue the bookdown command to generate the example files:cd _bookdown\/ .\/vendor\/bin\/bookdown book\/bookdown.json You should see some output logs indicating file reading and creation. The HTML will be generated at the root of {$REPO}, not in the _bookdown subdirectory. You should see two files, index.html and example.html.To browse these files, start the built-in PHP server on localhost:8080 (or some other port) and then use a web client to review them.php -S localhost:8080 -t {$REPO} Be sure to terminate the server when done."},{"id":"\/basic\/overview.html#2-1","title":"2.1. Overview","content":"Now that we have a working Bookdown installation, let's create some content and generate HTML from it. We need to deal with two things: our actual Markdown content files, and a bookdown.json config file to organize them."},{"id":"\/basic\/overview.html#2-1-1","title":"2.1.1. Markdown Content Files","content":"Bookdown uses CommonMark Markdown as its default markup. (Advanced users may write other conversion processes to use other markups.) This means that standard Markdown content is already suitable for use with Bookdown."},{"id":"\/basic\/overview.html#2-1-2","title":"2.1.2. The bookdown.json Config File","content":"The bookdown.json config file controls the title of our table-of-contents index page, and the content to be used for HTML generation. A bookdown.json config file looks like this:{ \"title\": \"My Title\", \"content\": [ \"page.md\", \"section\/bookdown.json\" ], \"target\": \".\/html\", \"template\": \"[path to Composer vendor]\/myname\/bookdown-templates\/templates\/main.php\", \"rootHref\": \"http:\/\/example.com\/\", \"tocDepth\": 2, \"copyright\": \"Copyright (c) 2016 <a href=\\\"http:\/\/bookdown.io\/\\\">Bokdown.io<\/a>\", \"extensions\": { \"commonmark\": [ \"Webuni\\\\CommonMark\\\\TableExtension\\\\TableExtension\", \"Webuni\\\\CommonMark\\\\AttributesExtension\\\\AttributesExtension\" ] } }  N.b.: The top-level bookdown.json has other elements that control book generation; we can ignore these for now. "},{"id":"\/basic\/overview.html#2-1-2-1","title":"2.1.2.1. Title String","content":"The \"title\" string determines the heading that will be used for the table-of-contents entry for the listed content."},{"id":"\/basic\/overview.html#2-1-2-2","title":"2.1.2.2. Content Array","content":"The \"content\" array specifies the order of pages, and the origins of those pages."},{"id":"\/basic\/overview.html#2-1-2-2-1","title":"2.1.2.2.1. Content String Elements","content":"Each content array element is an origin string. It determines both where the content is located, and the target name when rendering it into HTML. If the origin string ends in bookdown.json, the target name will the directory in which the bookdown.json file is stored, and the \"content\" in that bookdown.json file will be rendered into that directory. Otherwise, the target name is the same as the origin file name, minus any .ext file extension. The origin strings may point to: an absolute file path (with a leading directory separator) a file path relative to the bookdown.json file (no leading directory separator) a remote path, such as http:\/\/example.com\/path\/to\/page.md or http:\/\/example.com\/section\/bookdown.json  N.b.: The use of remote paths makes it possible to collect content from many different sources into a single book. "},{"id":"\/basic\/overview.html#2-1-2-2-2","title":"2.1.2.2.2. Content Object Elements","content":"Sometimes you will want the target name to be different from the origin name. In these cases, the \"content\" element can be an object of a single key-value pair, where the key is the target name and the value is the origin.The following is equivalent to the above:{ \"title\": \"My Book\", \"content\": [ {\"page\": \"page.md\"}, {\"section\": \"section\/bookdown.json\"} ] } The key (target name) can be any name you like, so the following uses the same origin files but sets different targets:{ \"title\": \"My Book\", \"content\": [ {\"alternative-page-name\": \"page.md\"}, {\"alternative-section-name\": \"section\/bookdown.json\", ] } "},{"id":"\/basic\/overview.html#2-1-2-2-3","title":"2.1.2.2.3. No \"index\" Content Names","content":"The target name index is reserved by Bookdown for table-of-contents pages. If you have an origin that will end up with an index target name, use a \"content\" object to rename it to something else."},{"id":"\/basic\/overview.html#2-1-2-3","title":"2.1.2.3. Target String","content":"The \"target\" string determines the folder where to store the generated HTML files."},{"id":"\/basic\/overview.html#2-1-2-4","title":"2.1.2.4. Template String","content":"The \"template\" string determines the path to main file of a 3rd party template which is installed via Composer for example. Please refer to the Advanced Topics section for more details."},{"id":"\/basic\/overview.html#2-1-2-5","title":"2.1.2.5. RootHref String","content":"The \"rootHref\" string is used to generate the full URL of the page links. This can be \/ or 'http:\/\/example.com\/' for example."},{"id":"\/basic\/overview.html#2-1-2-6","title":"2.1.2.6. TocDepth String","content":"The \"tocDepth\" string determines the depth of the table of contents. A value of 1 means that only H1 headings are displayed. The value 2 means that only H1 and H2 headings are displayed and so on. Value 0 means all headings will be displayed, this is the default value."},{"id":"\/basic\/overview.html#2-1-2-7","title":"2.1.2.7. Copyright String","content":"The \"copyright\" string is used in the footer to display the copyright of the documentation. HTML is allowed."},{"id":"\/basic\/overview.html#2-1-2-8","title":"2.1.2.8. Extensions Array","content":"The extensions array is used to extend the default Markdown parsing process with plugins. Actually only CommonMark extensions are supported. Please ensure that the extension classes are available via Composer autoloading."},{"id":"\/basic\/overview.html#2-1-2-8-1","title":"2.1.2.8.1. CommonMark Extensions","content":"The \"commonmark\" array is a list of CommonMark extension classes. All CommonMark extensions are supported which can be instantiated without any dependencies. The entry must be a FCQN of the extension class."},{"id":"\/basic\/adding-content.html#2-2-1","title":"2.2.1. Local Page Files","content":"Let's add a page to the existing example book. Use your favorite editor to create a file called new-page.md at {$REPO}\/_bookdown\/book. Add the following text to that file, and save when done:# My New Page Now is the time for all good men to come to the aid of their country. ## Dogs and Foxes The quick brown fox jumps over the lazy dog. It's not enough to create the file, though. We need to tell Bookdown that it exists, and what order it takes in our book. To do so, edit the bookdown.json file and add a new \"content\" element: \"content\": [ \"example.md\", {\"another\": \"new-page.md\"} }, Note that the Markdown file name does not have to match the HTML file name that will be generated. The new-page.md file will be transformed into another.html at generation time."},{"id":"\/basic\/adding-content.html#2-2-2","title":"2.2.2. Hierarchical Content","content":"In addition, you can specify another bookdown.json config file as a \"content\" element. When you do so, Bookdown will read that config file and treat its content as pages in a subsection. This allows you to structure books of any depth you like. For an example, review the files that produce this very site."},{"id":"\/basic\/generating-html.html#2-3","title":"2.3. Generating HTML","content":"Now that we have added some content, let's re-generate the HTML files."},{"id":"\/basic\/generating-html.html#2-3-1","title":"2.3.1. Setting The Target","content":"The top-level bookdown.json file has a \"target\" element that specified where the generated HTML should be saved. By default, this is the relative path ..\/..\/, meaning the root of our {$REPO} directory. If you like, you can change this to some other target directory."},{"id":"\/basic\/generating-html.html#2-3-2","title":"2.3.2. The bookdown Command","content":"Now we can actually generate the HTML output from our Markdown content. We do so by calling the bookdown command and passing it the path to our top-level bookdown.json config file. (Remember that {$REPO} is our root repository directory.)cd {$REPO}\/_bookdown .\/vendor\/bin\/bookdown book\/bookdown.json This will generate the HTML files to the \"target\" directory. To review them, start up the built-in PHP server using the \"target\" directory as the document root ...php -S localhost:8080 -t {$TARGET} ... and browse with the client of your choice.Note how Bookdown has done the following for us: Numbered the headings on each page Created a table-of-contents with the numbered headings Linked to each heading from the table-of-contents Added previous\/next\/up navigation on each page "},{"id":"\/basic\/generating-html.html#2-3-3","title":"2.3.3. Overriding The Target Value","content":"In some cases, you may find it necessary to temporarily override the target value from the top-level bookdown.json file. To do so, you can specify --target= when invoking the bookdown command:.\/vendor\/bin\/bookdown book\/bookdown.json --target=..\/..\/other-dir\/ "},{"id":"\/basic\/generating-html.html#2-3-4","title":"2.3.4. Overriding The RootHref Value","content":"In some cases you may find it useful to override the root-href value from the top-level bookdown.json file. To do so, you can specify --root-href= when invoking the bookdown command:.\/vendor\/bin\/bookdown book\/bookdown.json --root-href=http:\/\/example.com "},{"id":"\/basic\/publishing.html#2-4","title":"2.4. Publishing","content":"To publish the generated content, use git add and git commit on the various Markdown, JSON, and HTML files we have created, then push them to their origin. If the origin is Github Pages, then Github will automatically serve them for you. Alternatively, you can copy the files from the \"target\" directory wherever you like, or do with them whatever you wish."},{"id":"\/advanced\/remote.html#3-1","title":"3.1. Remote Content","content":" This requires the allow_url_fopen setting in php.ini to be enabled. You can specify remote Markdown and bookdown.json config files as \"content\" elements. This means you can collect pages and sections from various sources, where those pages and sections are maintained by their respective authors, and combine them into a single book.For an example of adding remote content, try setting the following \"content\" value:\"content\": [ \"https:\/\/raw.githubusercontent.com\/pmjones\/bookdown-demo\/master\/libraries\/_bookdown.json\" ] Then generate the book. You will see that Bookdown retrieves the remote content and generates it into local HTML files."},{"id":"\/advanced\/settings.html#3-2-1","title":"3.2.1. rootHref","content":"By default, all navgation links between pages will be prefixed with \/. Sometimes this will not be what you want; for example, if you are publishing your book to a subdirectory.If you want to use a different root href value, edit the top-level bookdown.json file and set the rootHref value:{ ... \"rootHref\": \"\/foo\/\", ... } Then all navigation links will be prefixed with \/foo\/ instead.This value is honored only at the root-level bookdown.json file."},{"id":"\/advanced\/settings.html#3-2-2","title":"3.2.2. tocDepth","content":"By default, the table of contents will show all content levels below it. You can limit the depth of the table of contents by setting the tocDepth value:{ ... \"tocDepth\": 2, ... } This value is honored at all levels of bookdown.json files."},{"id":"\/advanced\/styles.html#3-3","title":"3.3. Adding CSS Files","content":"By default, Bookdown does not come with any CSS files. The HTML output is functional, but not particularly stylish.To add CSS files: Place .css files of your choosing somewhere the \"target\" directory. Modify the {$REPO}\/_bookdown\/templates\/head.php file to add <link ... \/> tags for the .css files. Note that these should be linked relative to the \"target\" directory, not the Bookdown origin files. Regenerate the HTML and browse the results. Let's try an example.First, create a css\/ subdirectory in the \"target\" directory. By default, the \"target\" is the {$REPO} root.cd {$REPO} mkdir css Next, copy the following stylesheet to the css\/ subdirectory as style.css:body { font-family: sans-serif; } Then edit the {$REPO}\/_bookdown\/templates\/head.php override template file to add a link to the stylesheet.The file will end up looking something like this:<head> <title><?php echo $this->page->getTitle(); ?><\/title> <link rel=\"stylesheet\" type=\"text\/css\" href=\"\/css\/style.css\" \/> <\/head> (Note that the link HREF is in relation to the \"target\" directory.)Finally, regenerate the HTML files and browse through them. You should see that the stylesheet is now being honored on every page. N.b.: Because the css\/style.css file is static and not generated by Bookdown, you can edit it and re-browse the pages, and see the style changes immediately. "},{"id":"\/advanced\/templates.html#3-4","title":"3.4. Rendering","content":"Bookdown runs plain-PHP templates through Aura.View, using Aura.Html helpers, to render HTML pages.The default templates are located in the core Bookdown library; you can see them at {$REPO}\/_bookdown\/vendor\/bookdown\/bookdown\/templates\/. The project-specific override templates are located in the {$REPO}\/_bookdown\/templates directory."},{"id":"\/advanced\/templates.html#3-4-1","title":"3.4.1. Overriding The Default Templates","content":"You can override the default templates individiually or entirely to control Bookdown output. To do so: Copy the template you want to override from {$REPO}\/_bookdown\/vendor\/bookdown\/bookdown\/templates\/ to {$REPO}\/_bookdown\/templates. Modify the project-specific main.php template to point to the override version. Edit the override template as you see fit. Regenerate the HTML. For example, let's modify the navheader.php template.First, we copy the default template to the project-specific template location:cd {$REPO}\/_bookdown cp vendor\/bookdown\/templates\/navheader.php templates\/navheader.php Next, we open the project-specific copy of main.php and point to the new navheader.php location. Change the line that reads ...$templates->set(\"navheader\", \"{$library}\/navheader.php\"); ... to:$templates->set(\"navheader\", \"{$project}\/navheader.php\"); (Note that $library and $project are defined at the top of main.php.)Then we edit the navheader.php template and change it to whatever we like. Try something obvious, like replacing all the HTML and PHP code with <p>HI THERE<\/p>.Finally, regenerate the HTML. You should see HI THERE at the top of every page, but no navigation elements at all."},{"id":"\/advanced\/templates.html#3-4-2","title":"3.4.2. Choosing A Different Master Template","content":"If you like, you can point Bookdown to a completely different master template. In the root bookdown.json config file, specify a \"template\" value as the path to your new master PHP template:{ ... \"template\": \"..\/my-master.php\" } That template will be passed through an Aura.View instance.You can also completely rewrite the existing templates\/main.php template to whatever you like."},{"id":"\/advanced\/templates.html#3-4-3","title":"3.4.3. Overriding The Template Value","content":"In some cases, you may find it necessary to temporarily override the template value from the top-level bookdown.json file. To do so, you can specify --template= when invoking the bookdown command:.\/vendor\/bin\/bookdown book\/bookdown.json --template=..\/..\/other-template.php "},{"id":"\/advanced\/page-entity.html#3-5","title":"3.5. The Page Entity","content":"The Page entity is the central object around which pages are generated. There are three kinds of Page entity: Page represents every kind of page IndexPage is a special kind of Page that represents a table-of-contents index page RootPage is a special kind of IndexPage that represents the very first table-of-contents index page in the book A Page object is passed to every template script. You can use it to find out everything about where the page is in the system, and what the related configuration values are.A fuller description of the various Page entities is forthcoming. In the mean time, please examine the codebase itself for insight into the object properties and methods: Page, IndexPage, RootPage."},{"id":"\/development.html#4","title":"4. Development","content":"Bookdown needs your help! We are eager to bring in contributors who are interested in DocBook-like documentation, but without the heavy toolchain and XML of DocBook itself.If you are a developer, you can clone or fork the core library repository from Github. We plan to use the Issues as the main means of community communication. Pull Requests especially are appreciated, particularly for items on the Todo list.If you are a designer, you can already tell that we are design-challenged. It would be awesome if we could provide a good-looking stylesheet out-of-the-box for the Bookdown project skeleton. In addition, we are interested in figuring out a way to provide Composer-deliverable themes for Bookdown, so that other design-challenged developers can make their work look good."}]