npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

gitbook-plugin-regexplace

v2.1.2

Published

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

Downloads

548

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/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:

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 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:

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.