-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.hbt
140 lines (105 loc) · 6.61 KB
/
README.hbt
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
Metalsmith Simple Search
========================
This makes it really easy to add [Simple Jekyll Search](https://github.com/christian-fei/Simple-Jekyll-Search) to your Metalsmith project. Simply run all of your files through this plugin and it will generate your `search.json` file.
[![npm version][npm-badge]][npm-link]
[![Build Status][travis-badge]][travis-link]
[![Dependencies][dependencies-badge]][dependencies-link]
[![Dev Dependencies][devdependencies-badge]][devdependencies-link]
[![codecov.io][codecov-badge]][codecov-link]
Installation
------------
`npm` can do this for you.
npm install --save metalsmith-simple-search
Usage
-----
Metadata properties are copied to the resulting JSON objects, optionally passing through filters. First, this is an example that shows the default options in the JSON format. You do not need to specify any of these unless you want to override the default.
{
"plugins": {
"metalsmith-simple-search": {
"destinationJs": "simple-search.min.js",
"destinationJson": "index.json",
"index": {
"title": true,
"keywords": true,
"contents": "html"
},
"match": "**/*.{htm,html}",
"matchOptions": {},
"skipSearchJs": false
}
}
}
This is how you would use it in JavaScript. Again, these are the defaults and don't need to be specified unless you want to override what they do.
// Load the plugin
var simpleSearch = require("metalsmith-simple-search");
// Use this in your list of plugins.
.use(simpleSearch())
// Alternately, you can specify options. The values shown here are the
// defaults and can be overridden.
use(simpleSearch({
// Where to save the file that performs the JavaScript-based searches
// in a browser. Disable with the `skipSearchJs` setting.
destinationJs: "simple-search.min.js",
// Where to save the resulting JSON file that contains search words.
destinationJson: "search.json",
// Metadata fields to index and how to index them. A lengthier
// description follows after the example.
index: {
title: true,
keywords: true
contents: "html"
},
// Pattern of files to match so only some files are placed into the
// search index.
match: "**/*.{htm,html}",
// Options for matching files. See metalsmith-plugin-kit.
matchOptions: {},
// If true, do not write the `destinationJs` to the output files.
// When switching this on, make sure the "simple-search.min.js" file
// is somehow included in your build.
skipSearchJs: false,
// Transform the filename into a URL for the search engine. The
// result from this file is saved as the ".url" property in the
// per-file search object.
transformUrl: function (filename) {
return "/" + filename;
}
}));
This uses [`metalsmith-plugin-kit`] for matching files. It documents the options that can be used to control how files are matched.
The `index` property will determine how a particular file's metadata is indexed. It can be set to one of several values.
* `false` or `null` - Do not index this property. Great for overriding defaults.
* `true` - Index this property. If the value is an object, call `.toString()` on it first. If the value is an array, join with `" "`. Once it is a text string, index this as-is.
* `"html"` - Convert the value to a string then remove all HTML tags and unescape any escaped content. This means `<div class="xyz">text</div>` turns into `text` (HTML elements removed). The HTML is scanned for changed to lowercase, made into a list of keywords and duplicates are removed.
* `"markdown"` or `"md"` - Assume the value is markdown and remove some non-text markup. The markdown is changed to lowercase, made into a list of keywords and duplicates are removed.
* `"keywords"` - Change the text into lowercase, make it into a list of keywords and remove duplicates.
* `outStr = function (inStr)` - A custom function of your own that will take the string value of this metadata and convert it into a cleansed version.
You need to also use the `browser/jekyll-search.js` or `browser/jekyll-search.min.js` in the browser and configure it. Those files are included in this repository. To configure it you will need to execute some JavaScript on page load. Please see the [Simple Jekyll Search] site or the [browser/README.md](browser/README.md) file for great instructions on how to finish setting this up.
The only reason the `browser/` files exist in this repository is because the `jekyll-simple-search` npm module pulls in far too many dependencies (like gulp) during installation. I only want one build system, please.
Full API
--------
{{>main}}
Development
-----------
This uses Jasmine, Istanbul and ESLint for tests.
# Install dependencies.
npm install
# Run the tests
npm run test
This plugin is licensed under the [MIT License][License] with additional clauses. See the [full license text][License] for information.
[codecov-badge]: https://img.shields.io/codecov/c/github/connected-world-services/metalsmith-simple-search/master.svg
[codecov-link]: https://codecov.io/github/connected-world-services/metalsmith-simple-search?branch=master
[dependencies-badge]: https://img.shields.io/david/connected-world-services/metalsmith-simple-search.svg
[dependencies-link]: https://david-dm.org/connected-world-services/metalsmith-simple-search
[devdependencies-badge]: https://img.shields.io/david/dev/connected-world-services/metalsmith-simple-search.svg
[devdependencies-link]: https://david-dm.org/connected-world-services/metalsmith-simple-search#info=devDependencies
[Simple Jekyll Search]: https://github.com/christian-fei/Simple-Jekyll-Search
[License]: LICENSE.md
[metalsmith-hbt-md]: https://github.com/ahdiaz/metalsmith-hbt-md
[metalsmith-models]: https://github.com/jaichandra/metalsmith-models
[metalsmith-mustache-metadata]: https://github.com/connected-world-services/metalsmith-mustache-metadata
[metalsmith-plugin-kit]: https://github.com/fidian/metalsmith-plugin-kit
[metalsmith-relative-links]: https://github.com/connected-world-services/metalsmith-relative-links
[npm-badge]: https://img.shields.io/npm/v/metalsmith-simple-search.svg
[npm-link]: https://npmjs.org/package/metalsmith-simple-search
[travis-badge]: https://img.shields.io/travis/connected-world-services/metalsmith-simple-search/master.svg
[travis-link]: http://travis-ci.org/connected-world-services/metalsmith-simple-search