Readme.md: +minimal example and a bit of write-up

3 年前 · 086357806a
--- a/README.md
+++ b/README.md
@ -1,7 +1,73 @@
 # tpsearch

-**Work in Progress**
+**Work in Progress:**
+  * Needs cleanup
+  * Add minimal example
+  * either update pelican plugin `tipue_search` or the output-function must return to a rudimentary one.

-JavaScript based search engine for static websites
+JavaScript-based search engine for static websites

+tpsearch is a fork of Tipue Search, a JavaScript-based search engine. tpsearch allows searching over an array of pages or articles for search words. For example the static website generator pelican has a plugin (`tipue_search`), which emits a compatible JSON-object for use with tpsearch.

+At the moment, tpsearch assumes, that an object named `tipue_serach` exists, which contains all the article-information (e.g. generated by the pelican plugin `tipue_search` or similar plugins). The object is assumed to be of this scheme (newlines are ignored):
+
+```javascript
+var tipuesearch = { 
+    "pages": [
+        { "title": ... },
+        { ... }, 
+        ... 
+    ]
+}
+```
+
+## Depedencies
+
+A decently recent JavaScript engine would do. No additional libraries are needed.
+
+## Minimal Example
+
+A minimal working example will be added to the repository in the future. But here a very short set-up:
+
+You HTML will need the following:
+* include the JavaScript files
+* a search box
+* an area, where the search results are shown
+
+```html
+<html>
+<head>
+  <!-- ... -->
+  <!-- the content file, listing all your content, eg. from the plugin 'tipue_search' -->
+  <script src="/tipuesearch_content.js"></script>
+  <!-- the set-file contains strings, you may want to look into that to translate it to your language 
+       or add stop words, related words, user defined weighting for words,... -->
+  <script src="/static/js/tpearch_set.js"></script>
+  <!-- this is the file containing the magic -->
+  <script src="/static/js/tpsearch.js"></script>
+  
+  <script>
+  var tp = null;
+  // create new tpsearch-Object when the document has loaded
+  // this will initialise everything (i.e. it sets keyup-handlers, etc)
+  window.onload = function () {
+      tp = new tpsearch ( {
+          'show': 10,               // show 10 results per page
+          'descriptiveWords': 75,   // show 75 words per result
+          'newWindow': false,       // don't open a new page, when one clicks on a result
+          'minimumLength': 1,       // minimal length of the input to start tpsearch (default: 3)
+          'searchBox': '#tp_search_input',  // used for document.querySelector to find the search box
+          'outputBox': '#tp_search_results', // used for document.querySelector to find the results box
+      });
+  };
+  </script>
+</head>
+<body>
+  <input type="text" name="q" id="tp_search_input">
+  
+<div>
+  <div id="tp_search_results"></div>
+</div>
+</body>
+</html>
+```