Update all templates to use h1 as the root heading.

fnando · Jan 29, 2024 · 82f3625 · 82f3625
1 parent e6d5ad1
commit 82f3625
Show file tree

Hide file tree

Showing 12 changed files with 29 additions and 30 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,7 @@
 - Add support for frontmatter on `.md` and `.md.erb` files.
 - Wrap emoji with `span.emoji` and use a font for emojis so it renders the same
   in any system.
+- Update all templates to use h1 as the root heading.
 
 ## v3.1.0
 

diff --git a/README.md b/README.md
@@ -143,10 +143,8 @@ You'll want to see your progress eventually; it's time for you to generate the
 book PDF. Just run the command `kitabu export` and your book will be created on
 the `output` directory.
 
-Kitabu can generate a Table of Contents (TOC) based on your h2-h6 tags. The h1
-tag is discarded because it's meant to be the book title.
-
-To print the TOC, you need to print a variable called `toc`, using the eRb tag.
+Kitabu can generate a Table of Contents (TOC) based on your h1-h6 tags. To print
+the TOC, you need to print a variable called `toc`, using the eRb tag.
 
     <%= toc %>
 
@@ -276,7 +274,7 @@ declaration.
 Finally, to use this font, do something like this:
 
 ```css
-.chapter > h2 {
+.chapter > h1 {
   font-family: "Open Sans Condensed Bold";
 }
 ```

diff --git a/lib/kitabu/exporter/epub.rb b/lib/kitabu/exporter/epub.rb
@@ -115,7 +115,7 @@ def write_sections!
           File.open(section.filepath, "w") do |file|
             content = section.html.to_xhtml
 
-            page_title = section.html.css("h2").first.text.strip
+            page_title = section.html.css("h1, h2").first&.text.to_s.strip
             locals = config.merge(content:, page_title:)
 
             file << render_template(File.read(template_path), locals)

diff --git a/templates/assets/styles/html.css b/templates/assets/styles/html.css
@@ -72,7 +72,7 @@ li code {
   padding: 50px 0;
 }
 
-.chapter > h2 {
+.chapter > h1 {
   margin-top: 0;
 }
 
@@ -103,7 +103,7 @@ div.highlight pre {
   counter-increment: chapter;
 }
 
-.chapter h2:before {
+.chapter h1:before {
   content: var(--chapter-text) " " counter(chapter);
   display: block;
   text-transform: uppercase;

diff --git a/templates/assets/styles/pdf.css b/templates/assets/styles/pdf.css
@@ -155,8 +155,8 @@ a {
 }
 
 /* Section */
-.section > h2,
-.section--no-toc > h2 {
+.section > h1,
+.section--no-toc > h1 {
   text-transform: uppercase;
   font-family: "Open Sans Condensed";
   font-size: 40px;
@@ -173,7 +173,7 @@ a {
   height: 285px;
 }
 
-.section--no-toc > h2:before,
+.section--no-toc > h1:before,
 .section.changelog {
   content: "";
   display: block;
@@ -191,11 +191,11 @@ a {
   counter-increment: chapter;
 }
 
-.chapter > h3 {
+.chapter > h2 {
   margin-top: 40px;
 }
 
-.chapter > h2:before {
+.chapter > h1:before {
   content: var(--chapter-text) " " counter(chapter);
   display: block;
   font-size: 16px;

diff --git a/templates/templates/html/layout.erb b/templates/templates/html/layout.erb
@@ -22,7 +22,7 @@
     <section class="white-page"></section>
 
     <section class="section--no-toc table-of-contents">
-      <h2><%= I18n.t(:contents) %></h2>
+      <h1><%= I18n.t(:contents) %></h1>
       <div id="toc" class="two-columns">
         <%= toc %>
       </div>
@@ -36,8 +36,8 @@
 
     <section class="imprint section">
       <div>
-        <h2><%= I18n.t(:imprint, default: "Imprint") %></h2>
-        <h3><%= title %></h3>
+        <h1><%= I18n.t(:imprint, default: "Imprint") %></h1>
+        <h2><%= title %></h2>
         <p class="description"><%= subject %></p>
         <p class="creators"><%= creators.to_sentence %></p>
         <p class="copyright"><%= copyright %></p>

diff --git a/templates/text/01_Getting_Started.md b/templates/text/01_Getting_Started.md
@@ -1,4 +1,4 @@
-## Getting Started
+# Getting Started
 
 Hey! 👋
 
@@ -13,15 +13,15 @@ But before doing it so, you need to have some things installed:
 - The [Ruby](http://ruby-lang.org) interpreter version 3.2 or newer.
 - The [PrinceXML](http://princexml.com) converter version 14.0 or newer.
 
-### Installing Ruby
+## Installing Ruby
 
 To install Ruby, consider using [RVM](http://rvm.io) or
 [rbenv](http://rbenv.org), both available for Mac OSX and Linux distros. If
 you're running a Windows, well, I can't help you. I don't even know if Kitabu
 runs over Windows boxes, so if you find any bugs, make sure you
 [let me know](http://github.com/fnando/kitabu/issues).
 
-### Installing PrinceXML
+## Installing PrinceXML
 
 [PrinceXML](http://princexml.com) is the best HTML to PDF converter available.
 You can use advanced CSS features to style your book in any way you want. But
@@ -33,7 +33,7 @@ user costs 495USD. If you don't like the price tag, consider using
 To install PrinceXML, go to the website and download the correct version for
 your platform; you can choose from Mac OSX, to Linux and Windows.
 
-### Installing Calibre
+## Installing Calibre
 
 [Calibre](http://calibre-ebook.com/) is a e-book manager that, among other
 features, allows converting ePub files into .mobi files.

diff --git a/templates/text/02_Creating_Chapters.md b/templates/text/02_Creating_Chapters.md
@@ -1,4 +1,4 @@
-## Creating Chapters
+# Creating Chapters
 
 You can create chapters by having multiple files or directories. They're
 alphabetically sorted, so make sure you use a prefixed file name like

diff --git a/templates/text/03_Syntax_Highlighting.md.erb b/templates/text/03_Syntax_Highlighting.md.erb
@@ -1,6 +1,6 @@
-## Syntax Highlighting
+# Syntax Highlighting
 
-### What about the syntax
+## What about the syntax
 
 Kitabu uses [Rouge](http://rubygems.org/gems/rouge) as the syntax highlight
 formatter. It emits an output compatible with stylesheets designed for
@@ -74,7 +74,7 @@ You can select the theme by using the configuration `theme` on your
   <% end %>
 </ul>
 
-### Lexers
+## Lexers
 
 Rouge comes with dozens of lexers. Check out this list, generated dynamically
 when you export your e-book.

diff --git a/templates/text/04_Dynamic_Content.md.erb b/templates/text/04_Dynamic_Content.md.erb
@@ -1,4 +1,4 @@
-## Dynamic Content
+# Dynamic Content
 
 Sometimes you may find useful to generate content dynamically. Maybe you're
 going to read some configuration file, or maybe you just want to define some
@@ -15,7 +15,7 @@ created a helper that looks like this:
 To use it, I just needed to add `<%%= lexers_list %>` to my text file. This
 allows you to create anything you need!
 
-### Escaping ERb code
+## Escaping ERb code
 
 If you want to write a book about Rails, you're likely to use lots of ERb tags.
 In this case, make sure you escape the `<%% %>` and `<%%= %>` markers as

diff --git a/templates/text/05_Exporting_Files.md b/templates/text/05_Exporting_Files.md
@@ -1,4 +1,4 @@
-## Exporting Files
+# Exporting Files
 
 You can generate files as you go. Just execute `kitabu export` from your book's
 root directory.
@@ -86,7 +86,7 @@ $ bundle exec guard
 ** e-book has been exported
 ```
 
-### Exporting PDF with DocRaptor
+## Exporting PDF with DocRaptor
 
 After exporting your files, upload the `output` directory somewhere and make it
 available to the internet. Then you can even use curl to generate the pdf.

diff --git a/templates/text/06_Changelog.md b/templates/text/06_Changelog.md
@@ -2,8 +2,8 @@
 section: changelog
 ---
 
-## Changelog
+# Changelog
 
-### Not published yet
+## Not published yet
 
 - Initial version