docs: Add documentation

vivliostyle · Oct 3, 2024 · 4912a7e · 4912a7e
1 parent 322717c
commit 4912a7e
Show file tree

Hide file tree

Showing 18 changed files with 1,149 additions and 0 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1 @@
+index.md
diff --git a/docs/api-javascript.md b/docs/api-javascript.md
@@ -0,0 +1,3 @@
+## JavaScript API
+
+TODO
diff --git a/docs/config.md b/docs/config.md
@@ -0,0 +1,3 @@
+# Config Reference
+
+TODO
diff --git a/docs/cover-page.md b/docs/cover-page.md
@@ -0,0 +1,101 @@
+## Creating Cover Page
+
+If the configuration file `vivliostyle.config.js` specifies `cover: 'image.png'`, a cover HTML file `cover.html` will be generated and added as the cover page of the publication.
+
+The content of the generated cover HTML file will be as follows:
+
+```html
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Book Title</title>
+    <style data-vv-style>
+      body {
+        margin: 0;
+      }
+      [role="doc-cover"] {
+        display: block;
+        width: 100vw;
+        height: 100vh;
+        object-fit: contain;
+      }
+      @page {
+        margin: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <section role="region" aria-label="Cover">
+      <img role="doc-cover" src="image.png" alt="Cover image" />
+    </section>
+  </body>
+</html>
+```
+
+The `cover` can also be specified as an object with the following properties:
+
+- By specifying `src`, you can set the cover image to be loaded.
+- By specifying `htmlPath`, you can output the cover HTML file to a file other than `cover.html`. Setting it to `false` prevents the cover HTML file from being output. In this case, the cover page will not be included in the PDF output but will be set as the cover image when output in EPUB or WebPub format.
+- By specifying `name`, you can change the alt text of the cover image.
+
+```js
+cover: {
+  src: 'image.png',
+  htmlPath: 'toc.html',
+  name: 'My awesome cover image',
+},
+```
+
+### To output the cover page to a location other than the beginning of the publication
+
+By specifying `{ rel: 'cover' }` as an element of the `entry` array in the configuration file `vivliostyle.config.js`, the cover HTML file will be generated at that position.
+
+```js
+entry: [
+  'titlepage.md',
+  { rel: 'cover' },
+  'chapter1.md',
+  ...
+],
+cover: 'image.png',
+```
+
+With this, the first HTML file of the publication will be `titlepage.html`, followed by the cover HTML file `cover.html`.
+
+You can also add multiple cover pages. The following example adds different cover pages at the beginning and end of the publication.
+
+```js
+entry: [
+  {
+    rel: 'cover',
+    output: 'front-cover.html',
+  },
+  ...
+  {
+    rel: 'cover',
+    output: 'back-cover.html',
+    imageSrc: 'back.png',
+  },
+],
+cover: 'front.png',
+```
+
+### To customize the cover page
+
+* [Example: customize-generated-content](https://github.com/vivliostyle/vivliostyle-cli/tree/main/examples/customize-generated-content)
+
+To customize the cover page, specify the `path` and `output` of the cover file and `rel: 'contents'` as elements of the `entry` array in the configuration file as follows:
+
+```js
+entry: [
+  {
+    path: 'cover-template.html',
+    output: 'cover.html',
+    rel: 'cover'
+  },
+  ...
+],
+```
+
+Then, prepare the HTML file `cover-template.html` as the cover template. By including a tag `<img role="doc-cover" />` in `cover-template.html`, the cover image will be inserted at that part and the cover HTML file will be output to `cover.html`.
+
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -0,0 +1,106 @@
+# Getting Started
+
+Vivliostyle CLI is a command-line interface for typesetting HTML and Markdown documents. It includes the [Vivliostyle Viewer](https://docs.vivliostyle.org/#/vivliostyle-viewer) and generates high-quality PDFs suitable for publications.
+
+## Installation
+
+Ensure you have [Node.js](https://nodejs.org/) (v16 or later) installed.
+
+Install Vivliostyle CLI with the following command:
+
+```
+npm install -g @vivliostyle/cli
+```
+
+## Generating PDFs
+
+### Generate PDFs from HTML or Markdown
+
+Use the `vivliostyle build` command to generate a PDF from an HTML file. The default output PDF file name is "output.pdf".
+
+```
+vivliostyle build index.html
+```
+
+Similarly, specify a Markdown file to generate a PDF from the Markdown.
+
+```
+vivliostyle build manuscript.md -s A4 -o paper.pdf
+```
+
+For the Markdown syntax available in Vivliostyle CLI, refer to [VFM: Vivliostyle Flavored Markdown](https://vivliostyle.github.io/vfm/#/).
+
+### Specifying the output PDF file
+
+Specify the PDF file name with the `-o` (`--output`) option.
+
+```
+vivliostyle build book.html -o book.pdf
+```
+
+### Specifying a web URL
+
+You can also specify a web URL in addition to local HTML files.
+
+```
+vivliostyle build https://vivliostyle.github.io/vivliostyle_doc/samples/gutenberg/Alice.html -s A4 -o Alice.pdf
+```
+
+### Generate PDFs from other formats
+
+Vivliostyle CLI supports reading EPUB, unzipped EPUB OPF files, `pub-manifest` (web publication manifest JSON files), and `webbook` (HTML files with links to a table of contents or web publication manifest).
+
+```
+vivliostyle build epub-sample.epub -o epub.pdf
+vivliostyle build publication.json -o webpub.pdf
+```
+
+## Previewing the typesetting result
+
+Preview the typesetting result in a browser with the `vivliostyle preview` command. The browser will launch, allowing you to view the typesetting result with the Vivliostyle Viewer.
+
+```
+vivliostyle preview index.html
+vivliostyle preview manuscript.md
+vivliostyle preview epub-sample.epub
+```
+
+### Quickly preview publications composed of many documents
+
+To quickly preview publications composed of many documents, use the `-q` (`--quick`) option. This option uses rough page count estimation to load documents quickly (page numbers will be inaccurate).
+
+```
+vivliostyle preview index.html --quick
+vivliostyle preview publication.json --quick
+vivliostyle preview epub-sample.epub --quick
+```
+
+## Output formats other than PDF
+
+Vivliostyle CLI supports output in EPUB format and Web publications (WebPub) in addition to PDF format. For details, see [Special Output Settings](./special-output-settings).
+
+The matrix of supported output formats is as follows:
+
+| Input \ Output | `pdf` | `webpub` | `epub` |
+|---|:---:|:---:|:---:|
+| `pub-manifest` | 🔵 | 🔵 | 🔵 |
+| `markdown` | 🔵 | 🔵 | 🔵 |
+| `html` `webbook` (including external HTML) | 🔵 | 🔵 | 🔵 |
+| `epub` `epub-opf` | 🔵 | 🙅 | 🙅 |
+
+## Other options
+
+Display a list of available options in Vivliostyle CLI with the `vivliostyle help` command.
+
+```
+vivliostyle help
+vivliostyle help init
+vivliostyle help build
+vivliostyle help preview
+```
+
+Secret feature: Instead of the `vivliostyle` command, you can also use the command name `vs` to reduce the number of keystrokes slightly.
+
+See also:
+- [Vivliostyle CLI (README)](https://github.com/vivliostyle/vivliostyle-cli/blob/main/README.md)
+
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,15 @@
+# Vivliostyle CLI Documentation
+
+## Guide
+
+- [Getting Started](./getting-started)
+- [Themes and CSS](./themes-and-css)
+- [Using Config File](./using-config-file)
+- [Creating Table of Contents Page](./toc-page)
+- [Creating Cover Page](./cover-page)
+- [Special Output Settings](./special-output-settings)
+
+## API
+
+- [Config Reference](./config)
+- [JavaScript API](./api-javascript)
diff --git a/docs/ja/README.md b/docs/ja/README.md
@@ -0,0 +1 @@
+index.md
diff --git a/docs/ja/cover-page.md b/docs/ja/cover-page.md
@@ -0,0 +1,100 @@
+## 表紙ページの作成
+
+構成ファイル `vivliostyle.config.js` に `cover: 'image.png'` のような指定がある場合、表紙 HTML ファイル `cover.html` が生成されて、出版物の表紙ページとして追加されます。
+
+生成される表紙 HTML ファイルの内容は次のようになります。
+
+```html
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Book Title</title>
+    <style data-vv-style>
+      body {
+        margin: 0;
+      }
+      [role="doc-cover"] {
+        display: block;
+        width: 100vw;
+        height: 100vh;
+        object-fit: contain;
+      }
+      @page {
+        margin: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <section role="region" aria-label="Cover">
+      <img role="doc-cover" src="image.png" alt="Cover image" />
+    </section>
+  </body>
+</html>
+```
+
+`cover` はオブジェクト形式でも指定でき、以下のようなプロパティが指定できます。
+
+- `src` を指定すると、読み込ませる表紙画像を指定できます。
+- `htmlPath` を指定すると、目次の HTML ファイルを `cover.html` 以外に出力します。また、`false` を設定することで表紙 HTML ファイルを出力させないこともできます。このようにした場合、PDFでの出力には表紙ページが含まれずに、EPUBやWebPub形式で出力した場合の表紙画像として設定されます。
+- `name` を指定すると、カバー画像の代替テキストを変更します。
+
+```js
+cover: {
+  src: 'image.png',
+  htmlPath: 'toc.html',
+  name: 'My awesome cover image',
+},
+```
+
+### 表紙ページを出版物の先頭以外の場所に出力するには
+
+構成ファイル `vivliostyle.config.js` の `entry` の配列の要素として `{ rel: 'cover' }` を指定すると、その位置に表紙 HTML ファイルが生成されます。
+
+```js
+entry: [
+  'titlepage.md',
+  { rel: 'cover' },
+  'chapter1.md',
+  ...
+],
+cover: 'image.png',
+```
+
+これで、出版物の先頭の HTML ファイルは `titlepage.html` で、その次に目次の HTML ファイル `cover.html` という順番になります。
+
+また、複数の表紙ページを追加することもできます。以下の例は、最初と最後のページにそれぞれ別の表紙ページを追加する例です。
+
+```js
+entry: [
+  {
+    rel: 'cover',
+    output: 'front-cover.html',
+  },
+  ...
+  {
+    rel: 'cover',
+    output: 'back-cover.html',
+    imageSrc: 'back.png',
+  },
+],
+cover: 'front.png',
+```
+
+### 表紙ページをカスタマイズするには
+
+* [Example: customize-generated-content](https://github.com/vivliostyle/vivliostyle-cli/tree/main/examples/customize-generated-content)
+
+表紙ページをカスタマイズするには、次のように構成ファイルの `entry` の配列の要素として目次のファイルの `path` と `output`、`rel: 'contents'` を指定してください。
+
+```js
+entry: [
+  {
+    path: 'cover-template.html',
+    output: 'cover.html',
+    rel: 'cover'
+  },
+  ...
+],
+```
+
+そして、表紙のテンプレートとなる HTML ファイル `cover-template.html` を用意してください。`cover-template.html` の中に `<img role="doc-cover" />` というタグを用意することで、その部分に表紙画像が挿入された上で表紙の HTML ファイルが `cover.html` に出力されます。