feat: Support adding sections for generated ToC documents #484
Conversation
spring-raining
force-pushed
the
feat/improve-toc
branch
from
0b9d862
to
4cede7c
Compare
| title: entry.title || upath.basename(entry.target, '.html'), | ||
| href: encodeURI(upath.relative(distDir, entry.target)), | ||
| sections, | ||
| children: [], // TODO |
There was a problem hiding this comment.
This option is reserved for future updates.
|
EPUB出力とwebpub出力をテストしたところ問題がありました。 EPUB出力ディレクトリ これで
など。EPUBを解凍してcontent.opfファイルを見てみると、 <item id="manuscript01_computing-paradigmsxhtml" href="manuscript/01_Computing Paradigms.xhtml" media-type="application/xhtml+xml"></item>
<item id="manuscript02_algorithm-design-and-analysisxhtml" href="manuscript/02_Algorithm Design and Analysis.xhtml" media-type="application/xhtml+xml"></item>
<item id="manuscript03_systems-and-architecturexhtml" href="manuscript/03_Systems and Architecture.xhtml" media-type="application/xhtml+xml"></item>のように、URLにエスケープされていないスペースが入っていたり、 <spine>
<itemref idref="indexxhtml"></itemref>
<itemref></itemref>
<itemref></itemref>
<itemref></itemref>
</spine>のように、 webpub出力ディレクトリ 出力された "readingOrder": [
{
"url": "index.html",
"name": "Table of Contents",
"rel": "contents",
"type": "LinkedResource"
},
{
"url": "manuscript/01_Computing%20Paradigms.html",
"name": "Computing Paradigms"
},
{
"url": "manuscript/02_Algorithm%20Design%20and%20Analysis.html",
"name": "Algorithm Design and Analysis"
},
{
"url": "manuscript/03_Systems%20and%20Architecture.html",
"name": "Systems and Architecture"
}
],
"resources": [
"image.png",
"manuscript/01_Computing Paradigms.html",
"manuscript/02_Algorithm Design and Analysis.html",
"manuscript/03_Systems and Architecture.html",
"publication.json"
],"resources" に、"readingOrder" に出力されているHTMLファイル名が重複して出力されています。そして、それらのファイル名に含まれるスペースがエスケープされていません。 それから、"resources" に "publication.json" があるのも間違いだと思います。 |
文書titleとh1見出しに関してVFMでは文書titleをfrontmatterで指定しないと最初の見出しがtitleになるので、たとえばMDファイルが次のようにレベル1の見出しではじまる場合、 # Computing Paradigms
## Introduction to Computational Thinking生成される目次は次のようになります： <ol>
<li>
<a href="manuscript/01_Computing%20Paradigms.html"
>Computing Paradigms</a
>
<ol>
<li data-section-level="1">
<a
href="manuscript/01_Computing%20Paradigms.html#computing-paradigms"
>Computing Paradigms</a
>
<ol>
<li data-section-level="2">
<a
href="manuscript/01_Computing%20Paradigms.html#introduction-to-computational-thinking"
>Introduction to Computational Thinking</a
>いくつか問題があります。 文書titleとその文書の最初のh1見出しが同じでも重複して目次に出る1. Computing Paradigms
1. Computing Paradigmsのように、同じタイトルが目次に出ます。 "examples/table-of-contents/manuscript/01_Computing Paradigms.md" で、frontmatterでtitleを記述して、最初のレベル1見出しをsectionを生成しない section要素内の見出しだけを目次項目にするのでよいかどうかHTML仕様のHeading content では
とあります。つまりHeading contentの要素(h1-h6)は明示的にsectioning contentの要素(article, aside, nav, section)がなくても暗黙的なセクションの見出しとなるということです。この論理からすると、明示的なsection要素の有無によって目次の項目とするかどうかを決めるのはあまり適切でないかもしれません。 また、HTML仕様のsectioning contentには、section要素だけでなく、article、aside、nav要素もあります。これらの要素にある見出しも目次項目にしたい場合があるかと思います。たとえば、複数の記事(article)をまとめた出版物では各記事の見出しを目次項目にする必要があります。 section等の要素とは無関係に見出し要素h1-h6を目次項目にするほうがよいかもしれません。しかし、引用ブロック(blockquote)内の見出しは除外する必要があります。 見出しを目次項目にする場合には文書のtitleは使わないでよいのではたいていの場合、文書の最初のh1見出しはその文書（章など）のタイトルです。HTMLのtitle要素よりもそのh1要素を見出し項目にするほうが、次の利点があります：
preview中に文書titleを変更しても目次項目に反映されない不具合preview中に文書title（MDファイルのfrontmatterのtitle、またはfrontmatterなしの場合は最初の見出し）を変更しても目次に反映されません。たとえば、 "examples/table-of-contents/manuscript/01_Computing Paradigms.md" のfrontmatterの |
見出しのルビ要素などインライン要素が目次項目に反映されない見出しから目次項目を生成するとき、見出しに含まれるルビ要素などインライン要素が反映されず、テキストのみが使われるようです。たとえば見出し内の |
個人的にはメリットだけでなくデメリットもある仕様だと思うので、この部分はもう少し意見を募りたいです。 |
以下の条件のとき、タイトルを目次項目とせずにセクションの見出しをその文章の目次項目とするように仕様を変更しました。 d427d46
一方で、見出し要素を全て目次項目として列挙する動作は議論の余地があると思います。現実のHTMLでは本来のHeading contentの用途以外で
この意見をもとに、 |
hgroup要素の扱いhgroup要素 で目次がどうなるかテストしました。 "examples/table-of-contents/manuscript/01_Computing Paradigms.md" に次のsectionを追加してpreview <section>
<hgroup>
<p>p in hgroup</p>
<h2>H2</h2>
</hgroup>
<p>Paragraph</p>
</section>その結果は、生成された目次にhgroup要素の内容の要素が次のようにコピーされました。 <li>
<span>
<p>p in hgroup</p>
<h2>H2</h2>
</span>
</li>preview結果のスクリーンショット：
|
body要素の直下のh1なども同様にするべきでしょう。
「現実のHTMLでは本来のHeading contentの用途以外で 逆に、目次項目をsection（あるいはsectioning content）内の最初の要素である見出しに制限することは、次のような標準的なHTML文書内の見出しが除外される問題があります： <body>
<main>
<h1>Document Title</h1>
<section>
<header>
<h2>Section Title</h2>
<p>Paragraph in Header</p>
</header>
<p>Paragraph in Section</p>
…main要素内のh1要素はトップレベルにあるh1と同様に文書のトップレベルにの見出しとして扱われるべきだし、header要素内の見出しはheader要素が属するsectionの見出しとして扱われるべきだと思います。 目次の生成は基本的にHTML仕様の Headings and outlines に従うのがよいと思います。 "The outline is all headings in a document, in tree order." です。この all headings というのを |
resolve #254
Add a new
toc.sectionDepthoption that enables to add section heading titles to table of contents documents.Show section heading titles of
<h1>-<h4>vivliostyle.config.js:
Customize transform function that renders ToC documents
Each transform function should return the
Elementtype of hast format.vivliostyle.config.js: