{"id":19501217,"url":"https://github.com/gitbookio/gitbook-convert","last_synced_at":"2025-04-25T23:31:06.218Z","repository":{"id":73453441,"uuid":"49204373","full_name":"GitbookIO/gitbook-convert","owner":"GitbookIO","description":"CLI to convert an existing document to a GitBook.","archived":false,"fork":false,"pushed_at":"2016-09-05T09:50:18.000Z","size":115,"stargazers_count":109,"open_issues_count":15,"forks_count":19,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-04T05:11:11.050Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"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/GitbookIO.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":"2016-01-07T12:50:59.000Z","updated_at":"2025-02-23T12:04:29.000Z","dependencies_parsed_at":"2023-02-28T13:01:51.075Z","dependency_job_id":null,"html_url":"https://github.com/GitbookIO/gitbook-convert","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Fgitbook-convert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Fgitbook-convert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Fgitbook-convert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Fgitbook-convert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GitbookIO","download_url":"https://codeload.github.com/GitbookIO/gitbook-convert/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250912660,"owners_count":21506865,"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-11-10T22:11:54.122Z","updated_at":"2025-04-25T23:31:06.213Z","avatar_url":"https://github.com/GitbookIO.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gitbook-convert\n\n[![NPM version](https://badge.fury.io/js/gitbook-convert.svg)](http://badge.fury.io/js/gitbook-convert.svg)\n\n\u003e CLI to convert an existing document to a GitBook.\n\n## Install\n\nInstall this globally and you'll have access to the `gitbook-convert` command anywhere on your system.\n\n```shell\n$ npm install gitbook-convert -g\n```\n\n## Use\n\n```shell\n$ gitbook-convert [options] \u003cfile\u003e [export-directory]\n```\n\n### Options\n\n| Short | Long | Description | Type | Default |\n| ----- | ---- | ----------- | ---- | ------- |\n| -t | --document-title | Name used for the main document title | string | null |\n| -a | --assets-dir | Name of the document's assets export directory | string | assets |\n| -m | --max-depth | Maximum title depth to use to split your original document into sub-chapters | integer | 2 |\n| -p | --prefix | Prefix filenames by an incremental counter | flag | false |\n| -d | --debug | Log stack trace when an error occurs | flag | false |\n\nAfter converting your document, the corresponding GitBook files will be placed in the provided `export-directory` folder. The folder is created during conversion.\n\nIf `export-directory` is not provided, a new `export` folder is created in the current working directory. The GitBook files are then placed here.\n\nIf the `--document-title` argument is not passed, the filename without the file extension will be used as the main document title.\n\n### Currently accepted formats\n\n| Type | Extension |\n| ---- | --------- |\n| Microsoft Office Open XML Document | .docx |\n| OpenOffice / Open Document Format | .odt |\n| Docbook Markup Language | .xml |\n| HyperText Markup Language | .html |\n\n## Output\n\nThis version of `gitbook-convert` generates markdown files only. Support for asciidoc might be added later.\n\n### Document processing\n\n`gitbook-convert` divides your original document into chapters and sub-chapters, if any, one per output file. To do this, `gitbook-convert` automatically detects the headers in your document and uses the `-m` flag to split it into sub-chapters.\n\nWhen converting a Docbook file though, the depth is always detected automatically.\n\nThus, converting the following document named **History of modern computers.docx** with the default `--max-depth` flag:\n\u003e # Chapter 1\n\u003e What the world used to be.\n\u003e ## The beginning\n\u003e At the beginning was the big bang...\n\u003e ## The following\n\u003e Strange creatures called “humans” had trouble living in peace...\n\u003e # Chapter 2\n\u003e What the world is now.\n\u003e ## The awakening\n\u003e Computers came to rule the world...\n\u003e ## The end\n\u003e The power supply went disconnected.\n\nwill produce the following output:\n```shell\nuser @ cwd/export/history_of_modern_computers\n  README.md\n  SUMMARY.md\n  assets/\n  chapter_1/\n    README.md\n    the_beginning.md\n    the_following.md\n  chapter_2/\n    README.md\n    the_awakening.md\n    the_end.md\n```\n\nWhile using `1` for `--max-depth` would produce:\n```shell\nuser @ cwd/export/history_of_modern_computers\n  chapter_1.md\n  chapter_2.md\n  README.md\n  SUMMARY.md\n  assets/\n```\n\n### Summary\n\nThe `SUMMARY.md` file is created automatically.\n\nFor our first example:\n\n```markdown\n# Summary\n\n* [Introduction](README.md)\n* [Chapter 1](chapter_1/README.md)\n  * [The beginning](chapter_1/the_beginning.md)\n  * [The following](chapter_1/the_following.md)\n* [Chapter 2](chapter_2/README.md)\n  * [The awakening](chapter_2/the_awakening.md)\n  * [The end](chapter_2/the_end.md)\n```\n\nWith `--max-depth` set to `1`:\n\n```markdown\n# Summary\n\n* [Introduction](README.md)\n* [Chapter 1](chapter_1.md)\n* [Chapter 2](chapter_2.md)\n```\n\n### README\n\nThe content of the `README.md` file depends on your document structure. Anyways, the filename of your original document will be used as the main title here.\n\n##### Original document starts with a main header\n\n`gitbook-convert` creates the default GitBook `README.md` file:\n\n```markdown\n# History of modern computers\n\nThis file serves as your book's preface, a great place to describe your book's content and ideas.\n```\n\n##### Original document has an introduction\nOtherwise, everything before the first main header is used as the `README.md` content. If we modify our example to be:\n\n\u003e A short history of modern computers.\n\u003e # Chapter 1\n\u003e ## The beginning\n\u003e At the beginning was the big bang...\n\u003e ## The following\n\u003e ...\n\nThe content of the `README.md` file will be:\n\n```markdown\n# History of modern computers\n\nA short history of modern computers.\n```\n\nThe behavior is the same when `--max-depth` is set to higher levels. Each `README.md` in the sub-chapters folders will contain the preface for the current chapter.\n\n## Converters\n\nThe appropriate converter for a document type is deduced from its extension.\n\nFor now, the converters should:\n* be placed in `lib/converters`,\n* with its filename being the document-type extension, for example `/lib/converters/docx.js`,\n* added to the `lib/converters/index.js` file for reference and use.\n\n### docx\n\nThe `.docx` converter uses mwilliamson's [mammoth.js](https://github.com/mwilliamson/mammoth.js) to convert your document to HTML before generating the output.\n\n`gitbook-convert` will try to export your inline images in the `/assets` folder, using the image title as the image filename if provided.\n\n### odt\n\nThe `.odt` converter uses [odt2html](https://github.com/GitbookIO/odt2html) to convert your document to HTML before generating the output. Because there was no node module out there to convert OpenOffice documents to HTML, we built our own.\n\n`gitbook-convert` will try to export your inline images in the `/assets` folder, using the image name in the document as the image filename if provided.\n\n### docbook\n\n`gitbook-convert` requires [**xsltproc**](http://xmlsoft.org/XSLT/xsltproc.html) to be installed to process a Docbook. If you are using MacOS or a Linux distribution, it should be installed by default.\n\nYou can test that **xsltproc** is installed using:\n```shell\n$ which xsltproc\n```\n\n**xsltproc** uses the last version of [docbook.xsl](http://sourceforge.net/projects/docbook/files/docbook-xsl/) to convert your Docbook to HTML first. Since the [Docbook XML markup is very large](http://www.docbook.org/tdg5/en/html/chunk-part-d64e8789.html), `gitbook-convert` will try to convert the meta-data as well as possible. Extended conversion might be added to the tool based on user requests.\n\nWhen you install `gitbook-convert` using [npm](npmjs.com), the [docbook.xsl](http://sourceforge.net/projects/docbook/files/docbook-xsl/) stylesheets are downloaded and installed along with the app.\n\nWe recommend using the tool with Docbook version 5. [Here is a walk-through](http://doccookbook.sourceforge.net/html/en/dbc.structure.db4-to-db5.html) for converting an existing Docbook in version 4 to version 5.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitbookio%2Fgitbook-convert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgitbookio%2Fgitbook-convert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitbookio%2Fgitbook-convert/lists"}