gitbook-plugin-regexplace

General text replacement (RegExp -style) plugin for GitBook projects.

Initial problems:

• Using html code blocks directly on markdown pages often ruins rendering a GitBook page
• Similar type of content manipulation requires multiple plugins
• Indexing a book content

gitbook-plugin-regexplace is to resolve these problems with tech-savvy approach: using js regular expressions and replace functionality plus giving option to add mathes on book variables.

RegExp guide: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions

RexExr v2.0 builder: http://regexr.com

Usage examples

• Prevent page break on PDF/print
• Adding a container for image
• Counting and listing unique words on a book
• Using citations/footnotes

If you have new helpful use cases that could benefit plugin users, please send me a note so I can add new examples on this readme file: https://github.com/markomanninen/gitbook-plugin-regexplace

Prevent page break

Mark partitions on the page that should not break apart on printing the page or generating the page as a pdf.

Add the regexplace plugin on the plugins array of your book.json file and configure appropriate substitutes and texts to replace:

{
	"plugins": ["regexplace"],
	"pluginsConfig": {
		"regexplace": {
			"substitutes": [
				{"pattern": "<!-- nopb -->", "flags": "g", "substitute": "<div class=\"nopb\">"},
				{"pattern": "<!-- endnopb -->", "flags": "g", "substitute": "</div>"}
			]
		}
	}
}

Mark page partitions to text (markdown) files:

<!-- nopb -->

# Title

Normal content...

> additional text blocks

<!-- endnopb -->

This will produce:

<div class="nopb">
<h1>Title</h1>
<p>Normal content...</p>
<quote>additional text blocks</quote>
</div>

When above configuration is combined with the following website.css code block, it should prevent page breaks inside partitions, which are defined with div elements having a class nopb:

div.nopb {
    page-break-inside: avoid;	
}

Of course this also requires setting some style definitions for website and pdf generation on book.json similar to:

"styles": {
    "website": "media/website.css",
    "pdf": "media/website.css"
}

Adding a container for image

Next example is written with a help of RexExr v2.0 builder: http://regexr.com/3caon and inspired from the image-caption plugin of @todvora.

{
	"plugins": ["regexplace"],
	"pluginsConfig": {
		"regexplace": {
			"substitutes": [
				{
                   "pattern": "<img (.*)alt=\"([^\"]*)\"(.*) {0,1}\/{0,1}> {0,}{caption([^\\}]*)}", 
                   "flags": "g", 
                   "substitute": "<figure id=\"fig_PAGE_LEVEL_._INDEX_\"><img $1alt=\"$2\" $4$3><figcaption><span>Picture _PAGE_LEVEL_._INDEX_: </span>$2</figcaption></figure>"
                }
			]
		}
	}
}

This example also leverages _PAGE_LEVEL_ and _INDEX_ templates which are replaced by page level information for _PAGE_LEVEL_ and match index value for _INDEX_ in the gitbook-plugin-regexplace plugin.

Lets assume page.md has a level 1 and there is content something like this:

![Image 1](image.png){caption width=300}

![Image 2](image2.png){caption}

By using above regex substitutes it will produce output:

<figure id="fig1.1"><img scr="image.png" alt="Image 1" width=300><figcaption><span>Picture 1.1: </span>Image 1</figcaption></figure>

<figure id="fig1.2"><img scr="image2.png" alt="Image 2"><figcaption><span>Picture 1.2: </span>Image 2</figcaption></figure>

Which in turn can be styled with website.css to get nice image caption and container:

figure {
    margin: 1.5em 0px;
    padding: 10px 0;
    text-align: center;
}

figcaption {
    clear: left;
    margin: 0.75em 0px;
    text-align: center;
    font-style: italic;
    line-height: 1.5em;
    font-size: 80%;
    color: #666;
}

Screenshot from my GitBook project shown below:

Counting and listing unique words on book

Good way to do spell checking and text analysis is to count words on document and list them on test page. This can be achieved by regular expressions as well. First define configuration on book.json:

{
	"plugins": ["regexplace"],
	"pluginsConfig": {
		"regexplace": {
			"substitutes": [
				{
                    "pattern": "((?!([^<]+)?>)([0-9A-Za-z\\u0080-\\u00FF'.-]?)+(?!([^{]+)?})([0-9A-Za-z\\u0080-\\u00FF'])?(?!([^&]+)?;)([0-9A-Za-z\\u0080-\\u00FF']))",
                    "flags": "g",
                    "substitute": "$1",
                    "unreset": true,
                    "store": {
                        "substitute": "{$1}",
                        "unique": true,
                        "lower": true,
                        "variable_name": "words"
                    }
                }
			]
		}
	}
}

By using PAGE_PATH on store substitute we can get information on which page word is used, for example:

"substitute": "{_PAGE_PATH_#$1}"

But for now we just want to list all unique words in lower case and sorted alphabetically. Next step is to output words on any page you wish, say keywords.md:

# Words

Unique words in the book: {{ book.words.length }}

<hr/>

{{ book.words.sort().join(', ') }}

There you must be careful on printing words on the page, because they might also get counted on the final result. I have used output format {$1} for stored words and discounted them on pattern configuration: "pattern": "... (?!([^{]+)?}) ...". Also pattern "substitute": "$1" is important because you could easily replace all words on the book by this method. Here we recover match to the same position with $1.

Using citations

Again a specific pattern must be included on plugin configuration on book.json file:

{
    "pattern": "<!-- cite author=\"(.*?)\" title=\"(.*?)\" date=\"(.*?)\" location=\"(.*?)\" type=\"(.*?)\"(.*?) -->",
    "flags": "g",
    "substitute": "<sup><a id=\"cite_INDEX_\" href=\"references.html#ref_PAGE_LEVEL_._INDEX_\" title=\"$1: $2 $3\" type=\"$5\">_INDEX_</a></sup>",
    "store": {
        "substitute": "<span><a id=\"ref_PAGE_LEVEL_._INDEX_\" href=\"_PAGE_PATH_#cite_INDEX_\">_PAGE_LEVEL_._INDEX_.</a></span> <span>$1:</span> <span><a$6>$2</a></span> <span>$3</span> <span>$4</span>",
        "variable_name": "citations"
    }
}

This will find next text blocks from markdown pages, for example reflections.md:

<!-- cite author="wikipedia.org" title="Vesica Piscis" date="" location="" type="website" href="http://en.wikipedia.org/wiki/Vesica_piscis" -->

and replace it with html block:

<sup><a id="cite1" href="references.html#ref1.1" title="wikipedia.org: Vesica Piscis " type="website">1</a></sup>

which is a footnote link with autoincrement index per chapter.

On page for example references.md, you can use this code snippet to list all citations used on a book:

## Citations
<ul>
{% for cite in book.citations %}<li>{{ cite }}</li>{% endfor %}
</ul>
{% endif %}

Which will yield html:

<h2>Citations</h2>
<ul>
<li><span><a id="ref1.1" href="reflections.html#cite1">1.1.</a></span> <span>wikipedia.org:</span> <span><a href="http://en.wikipedia.org/wiki/Vesica_piscis" target="_blank">Vesica Piscis</a></span> <span></span> <span></span></li>
</ul>

The first link 1.1. is a reference back to the citation place.

If you want to list citations as footnotes at the end of each page/chapter, you could do separate include file, for example footnotes.md with the following code:

<ul>
{% for cite in book.citations %}
{% if cite.match(file.path) %}<li>{{ cite }}</li>{% endif %}
{% endfor %}
</ul>
{% endif %}

Then you can add that file on every page you want to support footnotes, presumely at the end of the file:

{% include 'footnotes.md' %}

One more small visual thing is to add these declarations to a stylesheet file, website.css:

sup {
    padding: 2px
}
ul.citations {
    margin-left: -30px;
}
ul.citations li:nth-child(1) {
    padding-top: 20px;
    border-top: 1px solid #BBB;
}
ul.citations li {
    font-size: 80%;
    list-style: outside none none;
}

Screenshot of output:

With gitbook-plugin-regexplace configuration patterns, substitutes, markdown templates and stylesheet you can manage a pretty detailed citation/footnote system on a GitBook project.