技術同人誌のテンプレートリポジトリです。新しい同人誌を作成するときは、このリポジトリを利用してください。
make run🔖 グローバル環境を可能な限り汚染せずに Markdown から組版の PDF を生成（ゆめみ大技林 '23）
表紙画像をプロジェクト内の book/cover/cover.png に保存している場合は、電子版 PDF と表紙画像の結合をコマンドで実行できます。次のコマンドで、表紙画像を結合した PDF output/ebook_covered.pdf を生成します。なお、電子版 PDF は事前に生成しておいてください。
make cover結合後の PDF に質の問題がある場合や、表紙画像がリポジトリ管理できない場合は、手動で結合（Acrobat Pro で PDF に画像を挿入するなど）してください。
次のコマンドで印刷入稿用 PDF が作成されます。
make pdf_pressもしくは、GitHub でタグに「n 版」または「n 版 m 刷」（たとえば、初版、初版2刷 や 第二版一刷 など）を付けてプッシュすると、電子版および印刷入稿用 PDF を添付したリリースが作成されます。cover ディレクトリに表紙画像や PSD ファイルがある場合は、それらもアセットに追加します。
書籍のタイトルの設定などは、book/vivliostyle.config.js ファイルで行います。
またテンプレートの都合上、年号等が最新に設定できないため、<!-- --> でコメントアウトしています。必要に応じて修正してコメントアウトを外してください。
原稿ファイルは book/manuscripts ディレクトリ以下に配置します。ディレクトリ構成は次のとおりです。
book/manuscripts/
├── articles/ # 記事ファイルを配置するディレクトリ
│ ├── your_chapter.md
│ └── images_your_chapter/
├── config/
│ ├── articles.yml # 記事の順番を制御するファイル（オプション）
│ ├── entry.yml # 本全体の構成順と目次表示を制御する設定（オプション）
│ └── generate.yml # 自動生成の設定（オプション）
├── generated/ # 自動生成されるファイル
│ ├── index.md
│ ├── authors.md
│ └── colophon.md
├── edited/ # 自動生成ファイルを手動編集するためのコピー先
│ ├── index.md
│ ├── authors.md
│ └── colophon.md
└── pages/ # はじめに・あとがきなど記事以外のページ
├── preface.md # はじめに
- book/manuscripts/articles ディレクトリ内に、拡張子
.mdの Markdown ファイルを作成します。 - PDF ビルド時に
articles/ディレクトリ内の Markdown ファイルが自動的に検出されます。book/vivliostyle.config.js を手動で編集する必要はありません。
各記事ファイルの先頭に次の front matter を記述してください。サンプル用のマークダウンファイルを参照してください。
---
class: content
title: 記事のタイトル
author: 著者名
profile: 著者の自己紹介文
---profile は YAML ブロックスカラー | で複数行で記述できます。改行は文末にスペース２つか <br> タグを設定してください。
profile: |
1 行目の自己紹介文です。
2 行目の自己紹介文です。config/articles.ymlが存在する場合: そのファイルに記載されたファイル名の順番で記事が設定されます。config/articles.ymlを削除した場合:articles/ディレクトリ内のファイルがアルファベット順で自動設定されます。
config/articles.yml の記述例：
# 記事の順番を制御するファイル（オプション）
# このファイルを削除すると、articles ディレクトリ内のファイルがアルファベット順で自動設定されます。
# 記事ファイルのファイル名のみを記載してください（パスは不要）。
- your_chapter.md
- another_chapter.md次のファイルが自動生成対象です。これらは編集者が対象であり、執筆者は対応不要です。
book/manuscripts/generated/index.md（目次）: 各記事のtitleを一覧化します。book/manuscripts/generated/authors.md（著者紹介）: 各記事のauthorとprofileを集約します。book/manuscripts/generated/colophon.md（奥付）: 書籍設定とgenerate.ymlから生成します。
yarn build / yarn build:press 実行時は、自動生成ファイルを毎回再生成します。
自動生成ファイルだけを更新したい場合は、次のコマンドを実行します。
yarn generate自動生成したファイルを手動編集したい場合は、次のコマンドで generated/ から edited/ へコピーします。
yarn editedited/index.md などが存在する場合、PDF ビルド時は generated/ より edited/ が優先されるため、再生成とのコンフリクトを避けられます。
本の構成順（vivliostyle.config.js の entry）は book/manuscripts/config/entry.yml で定義します。
type には次の固定値を使います。
generated: 自動生成ファイル（id: index | authors | colophon）page: 任意ページ（titleとfileが必要）articles: 記事一覧（articles.ymlまたはarticles/の自動検出）
toc フィールドで「目次ページ（generated/index.md）に表示する・しない」を制御できます。
- type: generated
id: index
toc: false
- type: page
title: はじめに
file: pages/preface.md
toc: true
- type: articles
toc: true
- type: generated
id: authors
toc: false
- type: generated
id: colophon
toc: falsebook/manuscripts/config/generate.yml で、著者紹介の出力フォーマットを変更できます。
{author}: 著者名{title}: 記事タイトル（同じ著者が複数執筆している場合は読点区切り）{profile}: プロフィール文
profile_template: |
### {author}（{title}）
{profile}book/manuscripts/config/generate.yml の articles_toc で、目次ページにおける記事の表示文字列を変更できます。
{title}: 記事タイトル{author}: 著者名{file}: 拡張子なしファイル名
title は front matter に無い場合、記事内の最初の H1 を使い、それも無ければファイル名を使います。
articles_toc: |
{title}({author})校正ツール textlint を利用して、文章校正ができます。なお、この lint ツールの使用は任意です。書き方で悩んだ・校正したい場合など、必要に応じて導入してください。
次のルールを導入しています。
- preset-ja-spacing
- 日本語周りにおけるスペースの有無を決定する
- preset-ja-technical-writing
- 技術文書向けの textlint ルールプリセット
- textlint-rule-spellcheck-tech-word
- WEB+DB 用語統一ルールベースの単語チェック
- （deprecated になっているので置き換えたい）
- Rules for TechBooster
- TechBooster の ルール を使用しています。
- iOS に関するルールはほとんどないので適宜追加してください。
その他、スペルチェックのルール textlint-rule-spellchecker がありますが、エディターのスペルチェックと競合しやすいので、今回は追加していません。VS Code を利用している場合は、プラグイン Code Spell Checker を追加すれば、スペルチェックが行われます。
make lintローカルに Node.js 環境がある場合は、VS Code のプラグイン taichi.vscode-textlint を導入することで、ファイル保存時に textlint が実行されます。
VS Code にプラグイン Dev Containers を追加します。コマンドパレット（ショートカットキー Command + Shift + P）を開いて、Remote-Containers: Reopen in Container を実行します。コンテナーが立ち上がったら、執筆を始めてください。ファイル保存時に textlint が自動実行されます。ただし、Docker を利用する場合は、ライセンスに注意して利用してください。
あるファイルを textlint の対象から外したい場合は .textlintignore にそのファイルを追加してください。また、ファイル内の特定の文章に対してルールを無効にしたい場合は、次のように記述してください。
<!-- textlint-disable -->
textlint を無効にしたい文章をここに書く
<!-- textlint-enable -->
ローカル環境に Node.js がインストールされている場合は、Docker を使わずにビルドできます。
次のコマンドで、ビルドに必要なツールをローカル環境にインストールします。
yarn installプレス版の PDF をビルドするには、Ghostscript および Xpdf も必要になります。次のコマンドでインストールします。
brew install ghostscript
brew install xpdfYarn を利用する場合は corepack を有効にしてください。
corepack enable
または
corepack enable yarnNode.js 24 以降では、scripts 配下の TypeScript ファイルも Node の組み込み TypeScript 実行でそのまま扱えます。追加のトランスパイラや ts-node は不要です。
yarn start: pdf を生成して開く（make run相当）yarn generate: 原稿ファイルを自動生成（make generate相当）yarn edit: 手動編集用に自動生成ファイルをedited/にコピー（make edit相当）yarn lint: textlint を実行（make lint相当）yarn build: pdf を生成（make pdf相当）yarn build:press: プレス版の pdf を生成（make pdf_press相当）yarn cover: 電子版 pdf と表紙画像を結合する（make cover相当）yarn open: pdf を開く（make open相当）yarn clean: 生成ファイルをすべて削除（make clean相当）
ローカルおよび CI で、@aikidosec/safe-chain を利用して、npm パッケージの安全性を確認できます。
@aikidosec/safe-chain の README にしたがって、ローカル環境にインストールしてください。なお、Docker を利用される場合は、安全確認したパッケージがインストールされるので原則的に対応不要です。
package.json の変更を含む PR が作成されたら、GitHub Actions でパッケージが確認されます。なお、Actions で利用する@aikidosec/safe-chain はバージョン固定しています。@aikidosec/safe-chain が更新されたら、それ自身の安全性を確認した後に、次のファイルを更新してください。
.github/workflows/aikidosec-safe-chain.ymlname: Install safe-chainのexport SAFE_CHAIN_VERSION=1.3.2で指定するバージョンを更新する
このプロジェクトは MIT ライセンスの下で公開されています。
- このリポジトリの MIT ライセンスには、ゆめみの紹介文は含まれません。