README.md 6.35 KB
Newer Older
Julie Blanc's avatar
Julie Blanc committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192

# Book index


A script to generate a book index. 


## Preparing your HTML

In the simplest terms, a book index is simply a key to locating information contained in a book. The main idea of the book index is to help the reader find information quickly and easily. It is not a way to locate in the book all the paragraph where the word "music" appears but to locate the places in the book where the word music is "revealing" in relation to the content. In this way, create an index is a semantic work that cannot be done automatically.

When you think your content is revelant and need to be in the index, simply add a span around the content:

```HTML
<p>General definitions of <span class="book-index" data-book-index="music">music</span> include common elements such as pitch, rhythm, dynamics, and the sonic qualities of timbre and texture.</p>
```

Your span must contain at least two elements:
- **a class**: this class is common to all index span elements of your document, you can name it as you wish
- **a data attribut**: this data attribut must be named `data-book-index`, it indicates the word(s) that will appear in the index
- you can also add an id if you want but it's not required

About the data attribute: 
- all data attributes containing the same word will be combined in a single line in the index, so you can use the same data attribute several times in your document
- it is possible to use spaces, capital letters and dashes in the data attribute, like this for example: `data-book-index="Wolfgang Amadeus Mozart"`
- it is also possible to format the text with the `<em>` en `<i>` elements (only): `data-book-index="<em>String Quartet in C major</em>"`

Finally, you must add somewhere in your HTML an element in which the book index will be generated. It can be a section or a div but it must be indicated by an id (that you name as you wish):

```HTML
<div id="book-index"></div>
```


## Use the script with paged.js


1. Add the `async` property to the paged.js script:
* if you use paged.js with npm: `<script async src="http://localhost:9090/dist/paged.polyfill.js"></script>`
* if you use the online script of paged.js: `<script async src="http://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>`

2. Add the book index script: 
```html
<script src="js/createIndex.js" type="text/javascript"></script>
```

3. Call the book index script:

The book index need to be generated before that paged.js fragmented the content into pages. You need to the hook `before` to call the script.   
Add this code in the `head` of you html document:

```html
<script>
    window.PagedConfig = {
      before: function () {
        createIndex({
            spanClassIndex: 'book-index',
            indexElement: '#book-index',  
            alphabet: true        
          });
      }
    };
  </script>
```

4. Use the print CSS properties in your stylesheet file to target the pages where the index elements appears: 

```CSS
.link-page a::after{ content: target-counter(attr(href), page); }

.link-page::after{ content: ", "; }

.link-page:last-of-type::after{ content: none; }

.index-value::after{ content: " – "; }
```


## Configuring the script
* `spanClassIndex`: define the id element where the toc list will be create
* `indexElement`: define the id element where the toc list will be create
* `alphabet`: choose if you want the alphabetical elements (`true`) or not (`false`)



## Styling the book index

The script generates a list whith items you can style. Here is an example of a book index generated: 

![Exemple of a generated book index](example-index.png)

```HTML
<ul id="list-index-generated">

  <li class="list-alphabet-element" id="alphabet-element-A">A</li>

  <li class="list-index-element" data-list-index="Apple">
    <span class="index-value">Apple</span>
    <span class="links-pages">
      <span class="link-page"><a href="#book-index-10"></a></span>
      <span class="link-page"><a href="#book-index-23"></a></span>
    </span>
  </li>

  <li class="list-index-element" data-list-index="Apricot">
    <span class="index-value">Apricot</span>
    <span class="links-pages">
      <span class="link-page"><a href="#book-index-15"></a></span>
      <span class="link-page"><a href="#book-index-35"></a></span>
    </span>
  </li>

  <li class="list-index-element" data-list-index="Avocado">
    <span class="index-value">Avocado</span>
    <span class="links-pages">
      <span class="link-page"><a href="#book-index-19"></a></span>
    </span>
  </li>

  <li class="list-alphabet-element" id="alphabet-element-B">B</li>

  <li class="list-index-element" data-list-index="Banana">
    <span class="index-value">Banana</span>
    <span class="links-pages">
      <span class="link-page"><a href="#book-index-2"></a></span>
      <span class="link-page"><a href="#book-index-38"></a></span>
      <span class="link-page"><a href="#book-index-12"></a></span>
    </span>
  </li>

  <li class="list-index-element" data-list-index="Blackberry">
    <span class="index-value">Blackberry</span>
    <span class="links-pages">
      <span class="link-page"><a href="#book-index-17"></a></span>
      <span class="link-page"><a href="#book-index-24"></a></span>
    </span>
  </li>

  <li class="list-alphabet-element" id="alphabet-element-C">C</li>

  <li class="list-index-element" data-list-index="Cherry">
    <span class="index-value">Cherry</span>
    <span class="links-pages">
      <span class="link-page"><a href="#book-index-32"></a></span>
      <span class="link-page"><a href="#book-index-27"></a></span>
    </span>
  </li>

  <li class="list-index-element" data-list-index="Coconut">
    <span class="index-value">Coconut</span>
    <span class="links-pages">
      <span class="link-page"><a href="#book-index-41"></a></span>
      <span class="link-page"><a href="#book-index-8"></a></span>
    </span>
  </li>

</ul>
```

An example of CSS to styling the book index:

![Exemple of a generated and styled book index](example-index-styled.png)


```CSS
#list-index-generated{
  list-style-type: none;
}

.list-alphabet-element{
  font-weight: bold;
  padding-top: 18px;
  padding-bottom: 9px;
  font-family: Arial, Helvetica, sans-serif;
}

.index-value{
  display: inline-block;
  min-width: 120px;
}
.index-value:first-letter{ text-transform: uppercase; }
.index-value::after{ content: "none"; }


.link-page a{ 
  text-decoration: none;
  color: currentColor;
  font-family: Arial, Helvetica, sans-serif;
  font-size: 12px;
}
```