gitbook-plugin-regexplace

Replace (RegExp -style) page section texts with given substitutes on GitBook projects

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
gitbook-plugin-regexplace
622.1.28 years ago8 years agoMinified + gzip package size for gitbook-plugin-regexplace in KB

Readme

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/RegularExpressions
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:
Image container

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 PAGEPATH 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:
Footnotes
With ``gitbook-plugin-regexplace`` configuration patterns, substitutes, markdown templates and stylesheet you can manage a pretty detailed citation/footnote system on a GitBook project.