Theme package copied in themes/packages/ should be customizable

[MurakamiShinyu]

npm package の vivliostyle theme を使用する場合、vivliostyle build コマンドでその theme package は themes/packages/ ディレクトリ内にコピーされます。たとえば Create Book で "theme-academic" をインストールして作業開始した場合、 vivliostyle.config.js の theme 設定は、

  theme: '@vivliostyle/theme-academic', // .css or local dir or npm package. default to undefined.

で、build を実行すると、

node_modules/@vivliostyle/theme-academic/

の内容が

themes/packages/@vivliostyle/theme-academic/

にコピーされています。

そのあと、このコピーされた theme package 内のCSSファイルなどを修正して、theme をカスタマイズしようとすることはよくあると思います。しかし、次に build を実行したとき、それらのファイル修正は破棄されて、node_modules からのコピーが再び行われるので、この方法での theme のカスタマイズは不可能です。

FAQの テーマをカスタマイズするには？ の方法でカスタマイズはできますが、分かりにくいと思います。

build のたびに常に theme package をリセットするという現在の動作は見直した方がよいのではないでしょうか？

修正案:

• build (previewも同様) 実行時、theme に指定された theme package がすでに themes/packages/ ディレクトリ内にあれば、node_modules からのコピーを行わない。
• workspaceDir や entryContextDir の指定がある場合は、build (previewも同様) 実行時、 entryContextDir 内の themes/packages/ 内に theme package がまだなければコピーする（カスタマイズ可能になる）。entryContextDir 内の theme の扱いについては関連issue Theme files/dirs in entryContextDir should be preserved in the output (#160) を参照。
• 変更を破棄して node_modules からのコピーをしなおすためのオプション --reset-theme なども必要かもしれない

[akabekobeko]

コピーをやめることに賛成ですが theme の npm を更新した際の反映をどうするか？という課題がありますね。

「npm 更新したら build の前に themes/ ディレクトリーを削除してください」のようにアナウンスするとしても、これを実行するとユーザーがカスタマイズした分も巻き添えになります。ぱっと思いつく方法だと

• vivliostyle.config.js の theme を entry のように Array とする
• themes/ は編集不可 (未サポート) としてカスタム CSS は theme へ別物として指定させる
• カスタム CSS は themes/ 以外へ配置してもらう

ですかね。開発者会議で複数 theme の話がありましたけど、あれが実現すれば解決でしょうか。

[MurakamiShinyu]

コピーをやめることに賛成ですが theme の npm を更新した際の反映をどうするか？という課題がありますね。

はい、「変更を破棄して node_modules からのコピーをしなおすためのオプション --reset-theme なども必要かもしれない」と書いたとき、変更を破棄するのではなく元の theme の更新をマージする機能もほしいと考えました。検討課題です。

• themes/ は編集不可 (未サポート) としてカスタム CSS は theme へ別物として指定させる

元の theme の更新とローカルの変更とをマージする機能がない間は、ローカルの変更をした場合は、元の theme の更新を簡単に反映させることはできないという制限があるのでよいと思います。一般のWebのスタイルシートのプロジェクトでもforkしてカスタマイズして利用していて、オリジナルのほうの更新を反映させるというのは両方とも変更が多いと簡単にはいかないので、vivliostyle theme についても同じことだと思います。

カスタム CSS を追加することでのカスタマイズの方法は、オリジナルでの更新を反映させやすいのでよい方法ですが、それを使うべきかどうかはケースバイケースです。CSSは、カスケーディングのしくみにより、複数のCSSファイルを指定して、あとから指定したCSSで最初のCSSでのスタイル指定を上書きすることなどができるのですが、この方法で思い通りにスタイルをカスタマイズするというのは簡単ではありません。複数の theme/CSS を指定できるようにすることには賛成ですが、それだけでは不十分だと思います。

vivliostyle theme の多くは SCSS で書かれると思います。SCSS を編集してカスタマイズできることが必要でしょう。
関連issue CLIにSCSSのトランスパイル機能を含める (#76)

そのようにして変更した theme を元 theme から fork した新しい vivliostyle theme package として公開するのが簡単にできるようになれば、vivliostyle themes のエコシステムにとってとてもよいと思います。

[spring-raining]

元テーマのCSSを編集して再利用したいというニーズについて理解しました。どういった形で実現するか考えていましたが、以下のような theme サブコマンドを導入することを提案します。

vivliostyle theme install

themeをインストールコマンドですが、内部的には npm install @vivliostyle/theme- と同様の動作になります。これまではthemeのインストールに npm や yarn を利用していましたが、vivliostyle コマンドに共通化することで npm や yarn の知識を要することなくインストールできる方が良いと考えました。また、専用のコマンドを通すことで、将来のバージョン固定化対応やDocker対応時のbreaking changeを無くせます。

vivliostyle theme eject

node_modulesにあるテーマファイルをプロジェクト直下のどこか (保存先は要検討) にコピーし、以降はそのファイルを参照するようにします。ejectという名称は、Vivliosyle管理下にあるthemeを切り離し、独自の管理下に置くというイメージです。

[spring-raining]

@MurakamiShinyu 「themeをコピーして編集しやすくすること」と「オリジナルのthemeの変更内容を反映させること」「forkしたテーマを新しいテーマとして公開すること」は個別に話したいので、このissueでは1つ目の内容について決めたいと思います。2, 3つ目の内容は別issueとして登録してもらえますか？

[AyumuTakai]

英語に疎いのでイメージ違いかもしれませんが、themeのコピー用コマンドの候補としてholdやkeepはいかがでしょうか。

ejectはどうにもCD-ROMドライブがう゛ぃーっと開くイメージが強くて。

[spring-raining]

eject というコマンド名はCreate react app から採用しました。

to make someone leave a place or building by using force ¹

とあるので、今回の意味からはそれほど離れていないと思いますがどうでしょうか？ 「detach」なども良いかと思います。

Footnotes

1. https://www.ldoceonline.com/jp/dictionary/eject ↩

[AyumuTakai]

個人の感覚ですが、node_modulesからejectするというよりvivliostyle-cliの管理下からejectするように捉えられそうだと感じたので候補を挙げさせていただきました。

反対意見というわけではありませんので、前例があるなら問題ないと思います。

[deadcoder0904]

i want to do this. currently, i'm using gutenberg theme using npm i @vivliostyle/theme-gutenberg

i like that theme but i want to modify it with custom css as well.

is it possible currently? also, i tried doing https://vivliostyle.org/faq/#how-to-customize-a-theme but there exists on file like theme.css. there is theme_common.css & lots of other css file but it doesn't have theme.css.

is there anyway to modify a theme especially gutenberg with custom css?

the only solution i see it is delete the theme & copy the contents from gutenberg into custom css.