{"id":16554089,"url":"https://github.com/pbinkley/jekyll-book","last_synced_at":"2025-12-04T04:08:21.535Z","repository":{"id":139698644,"uuid":"43794330","full_name":"pbinkley/jekyll-book","owner":"pbinkley","description":"A Jekyll and Bootstrap framework for publishing a book online in multiple formats.","archived":false,"fork":false,"pushed_at":"2016-09-17T17:17:28.000Z","size":944,"stargazers_count":24,"open_issues_count":0,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-04T19:44:40.844Z","etag":null,"topics":["minicomp"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pbinkley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-07T04:05:20.000Z","updated_at":"2024-12-14T22:53:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"381cf7b1-0b70-4d20-8988-933cec233662","html_url":"https://github.com/pbinkley/jekyll-book","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pbinkley/jekyll-book","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pbinkley%2Fjekyll-book","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pbinkley%2Fjekyll-book/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pbinkley%2Fjekyll-book/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pbinkley%2Fjekyll-book/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pbinkley","download_url":"https://codeload.github.com/pbinkley/jekyll-book/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pbinkley%2Fjekyll-book/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27490745,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-04T02:00:07.142Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["minicomp"],"created_at":"2024-10-11T19:50:34.849Z","updated_at":"2025-12-04T04:08:21.494Z","avatar_url":"https://github.com/pbinkley.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jekyll-book\nA Jekyll and Bootstrap framework for publishing a book online in multiple formats.\n\nThis project was forked from [travist/jekyll-kickstart](https://github.com/travist/jekyll-kickstart), a nice framework for starting a clean [Jekyll](https://jekyllrb.com/) \nsite with minimal [Bootstrap](http://getbootstrap.com/). Jekyll-Book extends it with a set of plugins, include files and conventions to support a book-like publication. A set of \n[Markdown](https://daringfireball.net/projects/markdown/) files are rendered into a sequence of interlinked pages, and also into a single PDF (and other output files) for downloading. \n\nAn example project: [Github repo](https://github.com/pbinkley/jekyll-book-marriage); [public site](https://www.wallandbinkley.com/rcb/works/marriage/)\n\n## Installation\n\n- Install Ruby (requires 2.0 or later)\n- [Install Pandoc](http://pandoc.org/installing.html) (with LaTeX support)\n- Clone this repository\n- In the repository directory, run ```bundle install``` to install the necessary gems\n- Run ```jekyll s``` to start the server\n- Visit the demo site at [http://127.0.0.1:4000/path/to/work/](http://127.0.0.1:4000/path/to/work/)\n\n## Customization\n\n### Metadata\n\nThe bibliographic metadata for the book is entered in ```_config.yml```:\n\n```\ntitle: Title of Book\nbrand: Title of Book\nsubtitle: Book has a subtitle\nauthor: Mary Author\ndate: 1918\ndescription: \u003e\n  Author, Title (Place: Publisher, Year)\n# description_latex is included in the PDF, so it uses LaTeX formatting\ndescription_latex: \u003e\n  Author, \\textit{Title} (Place: Publisher, Year)\neditor: Jim Editor\ntwitter: \"@mytwitterhandle\" # included \nlicense_icon: publicdomain # specified image in assets directory\nlicense_text: \"To the extent possible under law, Jim Editor has waived all copyright and related or neighboring rights to \\\"Title of Book\\\". This work is published from: Canada.\"\n# link back to this site in PDF; or just delete this line\njb_credit_latex: \"Generated with jekyll-book ¶ \\\\href{https://github.com/pbinkley/jekyll-book}{https://github.com/pbinkley/jekyll-book}\"\n# Info for CC license vcard in _includes/license.html\npublisher_url: \"http://www.domain.com/publisher/\"\ncountry_name: Canada\ncountry_code : CA\n```\n\nThe full citation should also be added to ```_includes/citation.html```.\n\n### Content\n\nContent files belong in the ```sections``` directory. They will be rendered according to the alphabetical order of file names, so they should be named accordingly.\n\nEach file should have a YAML metadata header:\n\n```\n---\nlayout: section               # invokes _layouts/section.html\ntitle: \"Chapter 2: Tables\"    # used in HTML head, jumbotron div, etc.\npermalink: 02-chapter2.html   # name of rendered file\nid: s02                       # used as id of article element, for chapter-\n                              #    specific CSS\ngroup: sections               # grouping in dropdown menus\n---\n```\n\n#### HTML filtering\n\nThe approach jekyll-books takes is to try to make the Markdown-to-HTML transformation work without intervention, and then to tweak the other transformations as needed. There are a few things, though, that get tweaked on the way to the HTML site. For example: to look good in the PDF, the Markdown files should begin with a second-level header title:\n\n```\n## Chapter 2: Tables\n```\n\nThis will appear in all of the downloadable versions. In the HTML, though, we want to suppress it, since the chapter title appears in the ```jumbotron``` div above the ```article``` div (and is drawn from the ```title``` property in the page's YAML block). Removing it is done in the ```_layouts/section.html``` template:\n\n\n```\n  \u003carticle id=\"{{ page.id}}\" class=\"post-content\"\u003e\n    {{ content \t    \t\n    \t| replace_regex: '\u003ch2.*\u003c/h2\u003e', '', true \n\t}}\n  \u003c/article\u003e\n```\n\nThe content of the article (which has already been rendered into HTML) is passed to the replace_regex method (defined in ```_plugins/replace.rb```), which replaces the first occurence of an ```h2``` heading with an empty string. More replacement operations could be chained together as needed.\n\n### Downloadable Formats\n\nIn addition to generating an HTML site in the normal Jekyll way, jekyll-book generates a set of downloadable files such as a PDF, containing the full text of the book. These downloads are generated by ```pandoc```; the full set of formats and the commands used to generate them are defined in the ```downloads``` section of ```_config.yml```:\n\n```\ndownloads:\n    pdf:\n      deps: [\"_config.yml\",\"_latex/jekyll-book.latex\",\"_scripts/preprocess.rb\"]\n      command: \"cat _config.yml sections/*.md | _scripts/preprocess.rb | pandoc --latex-engine=xelatex --template=_latex/jekyll-book.latex -f markdown+pipe_tables+footnotes -o %{dirDownloads}/%{slug}.pdf\"\n    epub:\n      deps: [\"_config.yml\",\"_epub-metadata.yml\",\"assets/cover.jpg\"]\n      command: \"pandoc -S --epub-cover-image=assets/cover.jpg --epub-metadata=_epub-metadata.yml -f markdown+pipe_tables+footnotes sections/*.md  -o %{dirDownloads}/%{slug}.epub\"\n    md:\n      deps: [\"_config.yml\"]\n      command: \"pandoc sections/*.md -t plain -o %{dirDownloads}/%{slug}.txt\"\n    txt:\n      deps: [\"_config.yml\"]\n      command: \"pandoc sections/*.md -o %{dirDownloads}/%{slug}.md\"\n```\n\n(These commands work in a \\*nix environment; they may need tweaking to run under Windows.) The generating of download files is handled by ```_plugins/renderdownloads.rb```, which determines which downloads need to be regenerated and runs the appropriate commands. The basename for these files (```%{slug}```) is computed by slugifying the ```brand``` property specified in ```_config.yml```. \n\nNew downloads are generated if the content or any of the dependencies (specified in the ```deps``` property) have been added, deleted or modified. The state of these files is tracked the same way ```git``` does, with SHA1 hashes stored in ```_data/previousrun.yml``` (the timestamp is not used). Preventing redundant regeneration allows users to avoid downloading newly-generated download files that are identical to the previous version. This is particularly important for the PDF, which includes a timestamp on the title page and therefore would appear to be a substantially new version when in fact nothing has changed but the timestamp.\n\n#### PDF\n\nPandoc uses LaTeX to generate PDFs, and jekyll-book uses a slightly customized LaTeX template: ```_latex/jekyll-book.latex```. Most of the customization is there to generate an informative title page using metadata properties drawn from ```_config.yml```. To enable this, ```_config.yml``` is passed as the YAML metadata block for the concatenated sequence of Markdown files. \n\nThe concatenated Markdown is fed through ```_scripts/preprocess.rb```. This script strips out the files' own YAML blocks, since we only want the ```_config.yml``` block to be present. It can be extended to make other changes, especially by substituting or adding LaTeX strings to achieve particular formatting effects. For example, a project that required certain paragraphs to be right-justified specified them in HTML in the raw Markdown:\n\n```\n\u003cp class=\"right\"\u003eLC\u003c/p\u003e\n```\n\nThis was handled by ```preprocess.rb``` like this:\n\n```\nif /\u003cp class=\\\"right\\\".*/.match(line)\n\tprint \"\\\\rightline{\" + /\\\u003e(.*)\\\u003c/.match(line)[1] + \"}\\n\"\n```\n\nGiving the output:\n\n```\n\\rightline{LC}\n```\n\nObviously, these hacks go beyond [\"the simple, clear, ASCII email inspired spirit of Markdown\"](https://blog.codinghorror.com/standard-flavored-markdown/) and should be kept to a minimum.\n\n#### EPUB\n\nThe EPUB generator hasn't had much attention yet but should be enhanced in the same way that the PDF one has, to make better use of the metadata and provide a better-looking template.\n\n### Dependencies\n\nThe following javascript and CSS libraries are included:\n\n* [jQuery](https://jquery.com/)\n* [jQuery Easing](https://github.com/gdsmith/jquery.easing)\n* [jQuery Fragment Scroll](https://github.com/miWebb/jQuery.fragmentScroll) ([forked](https://github.com/pbinkley/jQuery.fragmentScroll) and modified to handle incoming url fragments)\n* [Bootstrap](http://getbootstrap.com/)\n\nOther dependencies are listed in the Gemfile.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpbinkley%2Fjekyll-book","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpbinkley%2Fjekyll-book","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpbinkley%2Fjekyll-book/lists"}