Skip to content

Latest commit

 

History

History
348 lines (237 loc) · 14.4 KB

create-book.md

File metadata and controls

348 lines (237 loc) · 14.4 KB

Create Book

Introduction

Create Book makes an environment for creating a book. Write your manuscript using a template, customize it, and then use Vivliostyle CLI to generate your book. You do not need specialized HTML or CSS knowledge.

In this document, a PDF file that contains multiple pages is collectively referred to as a “book”. Vivliostyle is a library for making books of various formats. Create Book is a product that makes it easier to deliver Vivliostyle technology to more users.

Versions covered by this document

  • [v0.1.x]

Target readers of this document

  • Have some basic familiarity with running commands in a terminal
  • Have some basic knowledge about markdown notation
  • Would like to make the following types of books without any hassle:
    • technical books
    • academic articles
    • novels (vertical text is possible)
    • Slides

Create Book operating environment

  • macOS 10.13 (High Sierra) or higher
  • Windows 10
  • The following must be installed.
  • The following installations are also required to output PDF file for printing.

Steps to create a book

You can create a book by following these steps:

  1. Run Create Book and make a project folder.
  2. Move to the created project folder.
  3. Edit an existing markdown file and write a manuscript.
  4. Edit and customize vivliostyle.config.js.
  5. Npm runs Vivliostyle CLI to generate a book.

Because the project folders that are created are managed in git, git clients such as SourceTree allow you to make version-controlled work, such as comparing and reverting to the current version with the previous version (If versioning is unnecessary, it is perfectly safe to ignore it). Note that git is not discussed in this document. Please refer to various manuals and commentary sites.

About installation

The installation commands are as follows. <directory> is the name of the book's project folder that you want to create. Non-ASCII characters are not allowed.

npm create book <directory>

If the specified project folder already exists and the folder is not empty, Create Book will fail (the installation succeeds if the folder is empty).

In addition to npm, yarn is also available, but we will use the more common npm in this document.

During installation, you can specify the following items (fig-1). You don't have to specify everything here. If you do not want to specify it, you can skip to the next item by the return key (You can make changes later by editing vivliostyle.config.js below).

fig-1. Installing Create Book. You specify mybook as the project folder name. Although a warning comes out from npm, there is no effect on the user.
  • description (A brief description of the contents of the book. In addition to alphanumeric characters, kanji katakana hiragana can also be used)
  • author name (In addition to alphanumeric characters, kanji, katakana, and hiragana are also available)
  • author email
  • license (Select the type of distribution license with the up and down arrow keys)
  • choose theme (Select the type of theme package with the up and down arrow keys)
    • @vivliostyle/theme-bunko……Japanese novel style (vertical text).
    • @vivliostyle/theme-techbook……Technical books.
    • @vivliostyle/theme-slide……Slide document.
    • @vivliostyle/theme-academic……Academic articles.

In addition, the theme package is also OSS development. As development progresses, it may be added to other additions.

How Create Book works

The fig-2 below shows the contents of the actual folder installed (in this case, mybook) . Edit files from ❶ to ❸, to make a book to suit your own intentions.

fig-2 The contents of the mybook folder generated by the installation. Gray files and folders are invisible attributes.
  • ❶ manuscript.md ……Manuscript of the book in markdown format.
  • ❷ vivliostyle.config.js ……Setting files that customize books such as adding a format, table of contents, or a colophon.
  • ❸ package.json ……Configuration file for the entire project folder.

Create Book uses npm, a command line interface that comes with Node.js, one of the JavaScript execution environments, to made a book. During installation, Create Book does the following:

  • Create vivliostyle.config.js and package.json, which are configuration files referenced by npm.
  • Create a template for the manuscript, manuscript.md.
  • Install various libraries used by npm in the node_modules folder.

Npm refers to the above configuration file and, using the above library, drives Vivliostyle CLI to typesetting the manuscript.md, then output to a PDF file.

Writing manuscripts

You can write your manuscript by editing the "manuscript.md" (fog-2❶) file that is created when you install it as a template. The notation is VFM (Vivliostyle Flavored Markdown) that extends the standard Markdown GFM (GitHub Flavored Markdown) for books.

VFM is upward compatible with GFM. Therefore, if you are familiar with GFM, you can use GFM for the basic notation and you only need to learn VFM.

GFM (GitHub Flavored Markdown)

See the external site below.

VFM (Vivliostyle Flavored Markdown)

For detailed specifications, please refer to the following.

However, only the following items are implemented in the current version:

Other notation

Notes

It is not specified by GFM and VFM, but Endnotes are available in the notation of the following external sites.

Also, if you select the theme package '@vivliostyle/theme-techbook', footnotes are available using the following notation: However, it is a little cumbersome:

 <span class="footnote">text</span>

Tate-chu-yoko (Horizontal-in-Vertical)

If you select the theme package @vivliostyle/theme-bunko, you will be able to write Tate-chu-yoko (Horizontal-in-Vertical) by the following notation. For information on selecting a theme package, see Specify theme package below.

ええと<span class="tcy">4</span>×<span class="tcy">5</span>＝<span class="tcy">12</span>、<span class="tcy">4</span>×<span class="tcy">6</span>＝<span class="tcy">13</span>、<span class="tcy">4</span>×<span class="tcy">7</span>——ああ、もう！　そんな調子じゃいつまでも<span class="tcy">20</span>にならなくてよ！

Book customization

By editing vivliostyle.config.js (fig-2❷), you can customize the following:

Specify a title of a book

Specify title as follows to become a title of a book (the value is wrapped in single quotes: same as below).

title: 'mybook',

Specify a author name and e-mail address

The author name entered with author name during installation is the default, but if you specify the following, it takes precedence.

author: 'yamada <[email protected]>',

Specify a language to use

You can specify a language used in the book by removing the language comment-out (slash portion). The default English is en, and Japanese is ja. You can also specify the two-character code specified in ISO 639-1.

// language: 'ja',

↓

language: 'ja',

Specifying a format

You can specify the format by removing the size comment-out.CSS Paged Media Module Level 3 (7.1. Page size) can specify a following values. Note that a general B5 in Japan is JIS-B5 (as well as B4).

  • A5
  • A4 (default)
  • A3
  • B5
  • B4
  • JIS-B5
  • JIS-B4
  • letter
  • legal
  • ledger
// size: 'A4',

↓

size: 'JIS-B5',

Specify a theme package

A theme package specified as theme during installation is loaded by default, but if you specify any theme package here, it will be overridden.

theme: 'sample.css',

A theme package contains a CSS file that defines the style of the book. Please refer to A specification below.

The theme package can be obtained from the following.

Publication of multiple manuscripts

You can combine multiple markdown files into one book by specifying the following in the entry part as follows.

entry: [
    "filename1.md",
    "filename2.md",
    "filename3.md",
],

Add a table of contents

You can add a table of contents by following these steps.

  1. Prepare a markdown file for the following table of contents in advance, and save the file name as index.md in the project folder: Note that there must be an empty line between the line with the HTML tag and the markdown line. Otherwise, an error will occur.
# title of the book

<nav id="toc" role="doc-toc">

## table of contents

- [Article title1](filename1.html)
- [Article title2](filename2.html)
- [Article title3](filename3.html)

</nav>
  1. On the first line of entry in vivliostyle.config.js, specify the index.md that you provided.
entry: [
    "index.md",
    "filename1.md",
    "filename2.md",
    "filename3.md",
],

Add a colophon

You can add a colophon by following these steps.

  1. Prepare the following markdown file in advance and save the file name as colophon.md in the project folder: Note that there must be an empty line between the line with the HTML tag and the markdown line. Otherwise, an error will occur.
<section id="colophon" role="doc-colophon">

## 私が書いた本
20xx年x月x日　初版発行
- 発行　私が書いた本刊行会
- 編集　山田太郎
- 印刷　Sample Printing
© My Book Publishing, 20xx

</section>
  1. In the last line of entry in vivliostyle.config.js, specify the colophon.md that you provided.
entry: [
    "index.md",
    "filename1.md",
    "filename2.md",
    "filename3.md",
    "colophon.md",
],

Generation of a book

Npm scripts will generate a book using Vivliostyle CLI. The following command will output a PDF file with a same name as the project folder.

If you continue to run a same command, a last generated PDF file will be overwritten without warning. If you want to keep it, please be careful to evacuate to another place in advance.

npm run build

fig-3 Generating books using Vivliostyle CLI.

Generation of PDF files for four-color printing

You can create a four-color printable PDF file that conforms to the PDF/X-1a standard by editing package.json (fig-2❸) and adding the --press-ready option to the "vivliostyle build" section as follows.

"build": "vivliostyle build",

↓

"build": "vivliostyle build --press-ready",

When this option is specified, the entire image is rasterized only if the data contains transparent images such as drop shadows, resulting in a slight bleeding on the edges of the characters. It is not a big problem, but if you are worried, please consult with the printing office in advance. Acrobat Pro DC, etc. can be used to avoid this behavior by converting to PDF/X-4.

The following is a capture at the time of generation (fig-4).

fig-4 PDF file conforming to PDF/x-1a standard (4 colors).

limitations

The current version has the following limitations:

  • It is not possible to output to a PDF file including any cover image. If you want to use this feature, please use a PDF editor, such as Acrobat Pro DCand Preview (mac).
  • Grayscale print PDF file cannot be output. This problem can be avoided by converting it with Acrobat Pro DC.
  • If the directory name contains non-ASCII characters, an error occurs.

Afterword

As you can see from the version number, Create Book is still under development. And all Vivliostyle products are open source software. Please send us your thoughts and reports on how it should be done, what features are missing, or what errors you encountered. Of course, if you want to participate in development, you are welcome. For more information, please see the following page.