{"id":13484397,"url":"https://github.com/fnando/kitabu","last_synced_at":"2025-05-15T09:06:58.894Z","repository":{"id":404752,"uuid":"23352","full_name":"fnando/kitabu","owner":"fnando","description":"A framework for creating e-books from Markdown using Ruby. Using the Prince PDF generator, you'll be able to get high quality PDFs. Also supports EPUB, Mobi, Text and HTML generation.","archived":false,"fork":false,"pushed_at":"2024-02-18T07:46:59.000Z","size":15684,"stargazers_count":680,"open_issues_count":1,"forks_count":54,"subscribers_count":37,"default_branch":"main","last_synced_at":"2025-05-15T01:46:04.236Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fnando.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["fnando"],"custom":["https://paypal.me/nandovieira/🍕"]}},"created_at":"2008-06-08T05:15:13.000Z","updated_at":"2025-05-13T08:30:02.000Z","dependencies_parsed_at":"2024-05-01T10:35:55.781Z","dependency_job_id":"9917cb5c-3c0e-4f65-afd7-f8d69ccc3172","html_url":"https://github.com/fnando/kitabu","commit_stats":{"total_commits":292,"total_committers":15,"mean_commits":"19.466666666666665","dds":0.3321917808219178,"last_synced_commit":"bb01b3fbb386dd4f3c95e8a502f955abde9ee56f"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Fkitabu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Fkitabu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Fkitabu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fnando%2Fkitabu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fnando","download_url":"https://codeload.github.com/fnando/kitabu/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310515,"owners_count":22049469,"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","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":[],"created_at":"2024-07-31T17:01:23.667Z","updated_at":"2025-05-15T09:06:53.884Z","avatar_url":"https://github.com/fnando.png","language":"Ruby","readme":"# kitabu\n\n[![Tests](https://github.com/fnando/kitabu/workflows/ruby-tests/badge.svg)](https://github.com/fnando/kitabu)\n[![Gem](https://img.shields.io/gem/v/kitabu.svg)](https://rubygems.org/gems/kitabu)\n[![Gem](https://img.shields.io/gem/dt/kitabu.svg)](https://rubygems.org/gems/kitabu)\n[![MIT License](https://img.shields.io/:License-MIT-blue.svg)](https://tldrlegal.com/license/mit-license)\n\nKitabu is a framework for creating e-books from Markdown using Ruby. Using\nPrince PDF generator, you'll be able to get high quality PDFs. Also supports\nEPUB, Mobi, and HTML generation.\n\nWhile Prince is too expensive (495USD for a single user license), the free\nversion available at \u003chttp://www.princexml.com/download\u003e generates a PDF with a\nsmall logo on the first page, which is removed when sent to a printer; you can\nuse it locally for viewing the results immediately. When you're done writing\nyour e-book, you can use [DocRaptor](http://docraptor.com), which have plans\nstarting at \\$15/mo.\n\n## Features\n\n- Write using Markdown\n- Book layout support\n- Syntax highlight\n- Generate HTML, PDF, e-Pub (version 3.3), and Mobi\n- Table of Contents automatically generated from chapter titles\n\n## Installation\n\nTo install Kitabu, you'll need a working Ruby 3.2+ installation. If you're cool\nwith it, just run the following command to install it.\n\n    gem install kitabu\n\nAfter installing Kitabu, run the following command to check your external\ndependencies.\n\n    $ kitabu check\n\n    Prince XML: Converts HTML files into PDF files.\n    Installed.\n\n    Calibre's ebook-convert: Converts ePub e-books into .mobi files.\n    Installed.\n\nThere are no hard requirements here; just make sure you cleared the correct\ndependency based on the formats you want to export to.\n\n## Usage\n\nTo create a new e-book, just run\n\n    $ kitabu new mybook\n\nThis command creates a directory `mybook` with the following structure:\n\n```\n.\n├── Gemfile\n├── Gemfile.lock\n├── Guardfile\n├── assets\n│   ├── fonts\n│   ├── images\n│   │   ├── cover.png\n│   │   ├── kitabu.svg\n│   │   ├── markdown.svg\n│   │   └── up.svg\n│   ├── scripts\n│   └── styles\n│       ├── epub.css\n│       ├── html.css\n│       ├── pdf.css\n│       ├── print.css\n│       └── support\n│           ├── kitabu.css\n│           ├── normalize.css\n│           ├── notes.css\n│           └── toc.css\n├── config\n│   ├── helpers.rb\n│   ├── kitabu.yml\n│   └── locales\n│       └── en.yml\n├── templates\n│   ├── epub\n│   │   ├── cover.erb\n│   │   ├── page.erb\n│   │   └── toc.erb\n│   └── html\n│       └── layout.erb\n└── text\n    ├── 01_Getting_Started.md\n    ├── 02_Creating_Chapters.md\n    ├── 03_Syntax_Highlighting.md.erb\n    ├── 04_Dynamic_Content.md.erb\n    ├── 05_Exporting_Files.md\n    └── 06_Changelog.md\n\n13 directories, 28 files\n```\n\nThe `config/kitabu.yml` file holds some information about your book; so you'll\nalways change it.\n\nThe generated structure is actually a good example. So make sure you try it!\n\n![Kitabu - Sample Book](https://github.com/fnando/kitabu/raw/main/attachments/cover.png)\n\nThere's a generated sample available on the\n[attachments directory](https://github.com/fnando/kitabu/tree/main/attachments)\n• [PDF](https://github.com/fnando/kitabu/raw/main/attachments/kitabu.pdf) /\n[EPUB](https://github.com/fnando/kitabu/raw/main/attachments/kitabu.epub) /\n[MOBI](https://github.com/fnando/kitabu/raw/main/attachments/kitabu.mobi) /\n[HTML](https://github.com/fnando/kitabu/raw/main/attachments/browser-version.png).\n\nNow it's time to write your e-book. All your book content will be placed on the\ntext directory. Kitabu requires you to separate your book into chapters. A\nchapter is nothing but a directory that holds lots of text files. The e-book\nwill be generated using every folder/file alphabetically. So be sure to use a\nsequential numbering as the name. Here's a sample:\n\n    * text\n      * 01_Introduction\n        * 01_introduction.md\n      * 02_What_is_Ruby_on_Rails\n        * 01_MVC.md\n        * 02_DRY.md\n        * 03_Convention_Over_Configuration.md\n      * 03_Installing_Ruby_on_Rails\n        * 01_Installing.md\n        * 02_Mac_OS_X_instructions.md\n        * 03_Windows_instructions.md\n        * 04_Ubuntu_Linux_instructions.md\n\nIf you prefer, you can add a chapter per file:\n\n    * text\n      * 01_Introduction.md\n      * 02_What_is_Ruby_on_Rails.md\n      * 03_Installing_Ruby_on_Rails.md\n\nYou'll want to see your progress eventually; it's time for you to generate the\nbook PDF. Just run the command `kitabu export` and your book will be created on\nthe `output` directory.\n\nKitabu can generate a Table of Contents (TOC) based on your h1-h6 tags. To print\nthe TOC, you need to print a variable called `toc`, using the eRb tag.\n\n    \u003c%= toc %\u003e\n\n#### Frontmatter\n\nMarkdown files (and their `.md.erb` counterparts) support frontmatter, a section\nthat can inject variables to the page. Notice that the contents inside the `---`\ndelimiters must be valid YAML annotation and only basic types can be used\n(booleans, numbers, strings, nils and hashes/arrays with these same types).\n\nRight now there's only one special value called `section`, which defines the\nclass section when generating files. This allows you to have files inside your\n`text` directory that doesn't necessarily should have styling like regular\nchapters. For instance, this is how you can define a changelog section:\n\n```markdown\n---\nsection: changelog\n---\n\n## Changelog\n\n### Jan 26, 2024\n\n- Initial release\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e Notice that `section` will be retrieved from the first file, even if you have\n\u003e multiple files defining a section with a directory.\n\nThis meta data will be inject on your template using the variable `meta`. If you\nhave other variables, you could print them as `\u003c%= meta[\"varname\"] %\u003e`.\n\n### Using ERB\n\nYou can also have `.md.erb` files. You can mix Markdown and HTML, like the\nfollowing:\n\n    ## This the chapter title\n\n    \u003c%= image_tag \"myimage.png\" %\u003e\n\nThe above content must be placed in a `.md.erb` file. The generated content will\nbe something like this:\n\n```html\n\u003cimg src=\"images/myimage.png\" /\u003e\n```\n\nYou book's helpers can be added to `config/helpers.rb`, as this file is loaded\nautomatically by kitabu.\n\nYou can see available helpers on\n\u003chttps://github.com/fnando/kitabu/blob/main/lib/kitabu/helpers.rb\u003e.\n\n### Syntax Highlighting\n\nTo highlight code, use fenced code blocks.\n\n    ``` ruby\n    class User \u003c ActiveRecord::Base\n      validates_presence_of :login, :password, :email\n      validates_uniqueness_of :login, :email\n    end\n    ```\n\nYou can even provide options:\n\n    ```php?start_line=1\u0026line_numbers=1\n    echo \"Hello World\";\n    ```\n\n- We use [Redcarpet](https://rubygems.org/gems/redcarpet) for Markdown\n  processing.\n- We use [Rouge](https://rubygems.org/gems/rouge) for syntax highlighting.\n\nThe following Redcarpet options are enabled:\n\n- `autolink`\n- `fenced_code_blocks`\n- `footnotes`\n- `hard_wrap`\n- `highlight`\n- `no_intra_emphasis`\n- `safe_links_only`\n- `space_after_headers`\n- `strikethrough`\n- `superscript`\n- `tables`\n\n### Hooks\n\nThere are a few hooks that allows manipulating the content. You can use\n`before_render` and `after_render` to process the Markdown content. You can add\nsuch hooks to your `config/helpers.rb` file.\n\n```ruby\nKitabu::Markdown.add_hook(:before_render) do |content|\n  # manipulate content and return it.\n  content\nend\n\nKitabu::Markdown.add_hook(:after_render) do |content|\n  # manipulate content and return it.\n  content\nend\n```\n\n### Using custom fonts\n\nYou can use custom fonts on your ebooks. Just add them to the `fonts` directory\n(you can create this directory on your book's root directory if it doesn't\nexist).\n\nThen, on `assets/styles/support/fonts.css` you can add the `@font-face`\ndeclaration.\n\n```css\n@font-face {\n  font-family: \"Open Sans Condensed Bold\";\n  src: url(\"../../fonts/OpenSans-CondBold.ttf\");\n}\n```\n\nFinally, to use this font, do something like this:\n\n```css\n.chapter \u003e h1 {\n  font-family: \"Open Sans Condensed Bold\";\n}\n```\n\nInstead of doing the above manually, you can also use Prince's `--scanfonts`\noption.\n\n```console\n$ prince --scanfonts assets/fonts/* \u003e assets/styles/support/fonts.css\n```\n\nJust remember to replace the generated path to be something like `../../fonts`\ninstead.\n\n\u003e [!TIP]\n\u003e\n\u003e In most cases, it's easier to redefine `sans-serif`, `serif` and `monospace`\n\u003e fonts. To know more about how to do this, read Prince's\n\u003e [Redefining the generic font families](https://www.princexml.com/doc/styling/#redefining-the-generic-font-families)\n\u003e documentation.\n\nIf you're unsure if fonts are actually being used on PDF files, use the\nenvironment variable `PRINCEOPT` to disable system fonts.\n\n```console\n$ PRINCEOPT='--no-system-fonts --debug --log output/prince.log' kitabu export --only pdf\n=\u003e e-book couldn't be exported\n\n$ tail -n10 output/prince.log\nSat Jan 27 18:39:10 2024: debug: font request: Caslon, serif\nSat Jan 27 18:39:10 2024: warning: Ensure fonts are available on the system or load them via a @font-face rule.\nSat Jan 27 18:39:10 2024: warning: For more information see:\nSat Jan 27 18:39:10 2024: warning: https://www.princexml.com/doc/help-install/#missing-glyphs-or-fonts\nSat Jan 27 18:39:10 2024: internal error: Unable to find any available fonts.\nSat Jan 27 18:39:10 2024: finished: failure\nSat Jan 27 18:39:10 2024: ---- end\n```\n\n### Configuring Markdown\n\nKitabu uses [Redcarpet](https://github.com/vmg/redcarpet) as the Markdown\nengine. You can override the default processor by setting\n`Kitabu::Markdown.processor`. This can be done by adding something like the\nfollowing to `config/helpers.rb`:\n\n```ruby\nKitabu::Markdown.processor = Redcarpet::Markdown.new(\n  Kitabu::Markdown::Renderer.new(hard_wrap: false, safe_links_only: true),\n  tables: true,\n  footnotes: true,\n  space_after_headers: true,\n  superscript: true,\n  highlight: true,\n  strikethrough: true,\n  autolink: true,\n  fenced_code_blocks: true,\n  no_intra_emphasis: true\n)\n```\n\nThe above options are Kitabu's defaults.\n\n### Exporting PDFs using DocRaptor\n\nIf you're not planning to buy PrinceXML, consider using\n[DocRaptor](http://docraptor.com). Here's how you can easily do it:\n\n```bash\ncurl -H \"Content-Type:application/json\" -d'{\"user_credentials\":\"YOUR_CREDENTIALS_HERE\", \"doc\":{\"name\":\"kitabu.pdf\", \"document_type\":\"pdf\", \"test\":\"false\", \"document_url\":\"https://example.com/output/kitabu.pdf.html\"}}' http://docraptor.com/docs \u003e kitabu.pdf\n```\n\n## References\n\n- Markdown: \u003chttp://daringfireball.net/projects/markdown/syntax\u003e\n- Markdown PHP: \u003chttps://michelf.ca/projects/php-markdown/extra/\u003e\n- Some PrinceXML tips by the creator himself: \u003chttps://css4.pub\u003e\n\n## Legal Notes\n\n- PrinceXML: [license](http://www.princexml.com/license/)\n\n## Maintainer\n\n- [Nando Vieira](https://github.com/fnando)\n\n## Contributors\n\n- https://github.com/fnando/kitabu/contributors\n\n## Contributing\n\nFor more details about how to contribute, please read\nhttps://github.com/fnando/kitabu/blob/main/CONTRIBUTING.md.\n\n## License\n\nThe gem is available as open source under the terms of the\n[MIT License](https://opensource.org/licenses/MIT). A copy of the license can be\nfound at https://github.com/fnando/kitabu/blob/main/LICENSE.md.\n\n## Code of Conduct\n\nEveryone interacting in the kitabu project's codebases, issue trackers, chat\nrooms and mailing lists is expected to follow the\n[code of conduct](https://github.com/fnando/kitabu/blob/main/CODE_OF_CONDUCT.md).\n","funding_links":["https://github.com/sponsors/fnando","https://paypal.me/nandovieira/🍕"],"categories":["RUBY","PDF","Happy Exploring 🤘","Awesome Ruby CLIs","Ruby"],"sub_categories":["Converting"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnando%2Fkitabu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffnando%2Fkitabu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnando%2Fkitabu/lists"}