Security News
tea.xyz Spam Plagues npm and RubyGems Package Registries
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
helpserver
Advanced tools
Readme
A library used to automate generation of table of contents from directory structure, and optionally populate and query against an elasticsearch index to perform full text search of static help files.
npm install helpserver
The helpserver processes the HTML to extract the plaintext for performing text search against, but it also looks for comments and classes.
Metadata is included on a page in the form of a comment "<!---HELPMETADATA:" - for example:
<!---HELPMETADATA: { "tags" : "expert" } --->
Changing the location of a help pages location in the table of contents - the group metadata tag, this can be relative - for example.
<!---HELPMETADATA: { "group" : "Subtopic" } --->
Will move the page to aunder a child branch called 'subtopic'.
<!---HELPMETADATA: { "group" : "../Sibling/Kid" } --->
Will move the page to under a Kid topic under the Sibling topic that gets added a level up.
<!---HELPMETADATA: { "group" : "/New Features/Create Document" } --->
Will move the page to an absolute position in the TOC (top level branch 'New Features' under sub topic 'Create Document'
This is used by the filter logic to allow a subset of the pages to be exposed based on content (i.e show me 'expert' pages).
If a div of class 'helpserver_toc' exists in a page, we look for ul and li tags that contain anchor tags that reference the document, for example if your help page contains this
<div class="helperserver_toc" >
<ul>
<li><a href="#Intro">Intro</a> </li>
<li><a href="#API">API</a>
<ul>
<li><a href="#Query">Query</a> </li>
<li><a href="#Metadata">Retrieve Metadata</a> </li>
</ul>
</li>
</ul>
</div>
Then helpserver will add child tags of 'Intro', 'Api' with children 'Query' and 'Retrieve Metadata' for the help page.
The editToc setting points to a help page in the help folder that will be displayed on the documentation page when no sections are selected.
Using helperserver_toc in the top level page changes the structure at the top - in addition to an id, the anchor tags in the li tags support an attribute of 'helpserver_folder' to include branches of the tree. another optional attribute called helperserver_flatten will automatically flatten folders with 'helperserver_flatten' or fewer entries.
For example, if you had a folder structure of your help system like this:
/help/Guide
/help/Guide/HasOnePage
/help/Tutorial
/help/Tutorial/Hello World
/help/Tutorial/Complex Application
/help/API
/help/API/Client-Side
/help/API/Server-Side
And a main help page called "main.html" that was assigned through having the "editToc" set to "main.html" in the settings file. The leaf nodes of the ui/li tree that have helpserver_folder will get populated with the specified branch of help - if there are folder beneath a level, the folders will be added recursively.
The helperserver_flatten=1 on the Guide ensures that the folder HasOnePage (which in this example contains a single help page) will be removed from the table of contents and treated as a sibling of the other pages in Guide. Not surprisingly, if we used helperserver_flatten=2, then a folder with two of fewer help pages would have been 'flattened' into the parent level.
contents of /help/main.html
<div class="helperserver_toc" >
<ul>
<li><a href="#/Guide" helpserver_folder="/Guide" helperserver_flatten="1" >Guide</a> </li>
<li><a href="#/Tutorial" helpserver_folder="/Tutorial" >Tutorials</a> </li>
<li><a href="#/API">API</a>
<ul>
<li><a href="#/API/Client-Side" helpserver_folder="/API/Client-Side">Client Side API</a> </li>
<li><a href="#/API/Server-Side" helpserver_folder="/API/Server0-Side">Server Side API</a> </li>
</ul>
</li>
</ul>
</div>
<h1 name="/Guide" >Guide</h1>
The guide will give you an overview of the features.
<h1 name="/Tutorial" >Tutorials</h1>
The Tutorials will provide hands on experience with the product.
<h1 name="/API" >Client and Server side API</h1>
There are different APIs for the client side and the server side.
<h1 name="/Client-Side" >Client Side API</h1>
API's that you can program on the client side using HTML5 & javascript
<h1 name="/Server-Side" >Server Side API</h1>
API's you can use of the Server side for business logic
The help server includes the methods
.expressuse(req, res)
To handle top level express route (let helpserver handle all the routing).
.status(function(stats) {})
To get the status, including whats been generated, and if the index provider is running (in the case of using search, you will want elasticsearch to be started before you start using the search related api calls).
.generate(callback(err,result) {});
To generate the help table of contents.
.buildindex(callback(err,result) {});
To populate the search index with plaintext content of the help pages. If a filter is defined, after the index is built, a table of contents that applies the filter is defined.
.refresh(callback(err,result) {});
To regenerate the help table and incrementally update only those pages that changed.
.search(pattern, callback(err,data) {})
To search the index for a pattern.
.get(page,callback(err,data,type) { });
To retrieve a help page or resource.
.gettree(page,allowEncoding,callback(err,data) { });
To retrieve the html tree (generated ul) , allowEncoding is the encoding we expect (i.e. deflate returns a gzip deflated version).
.gettreejson(page,allowEncoding,callback(err,data) { });
To retrieve the json tree ( text and paths ) , allowEncoding is the encoding we expect (i.e. deflate returns a gzip deflated version).
The helpserver class requires some initialization parameters, which include
Example custom responseHeader - Enable CORS access to page - useful if you want to be able to embed helpserver in a site that is on another domain.
"responseHeader" : {
"Access-Control-Allow-Origin" : "*" ,
"Access-Control-Allow-Headers" : "Origin, X-Requested-With, Content-Type, Accept"
} ,
Generating a table of contents from a folder structure. In the following example, we want to create a table of contents file that from a directory structure and contained html files.
var Help = require('helpserver');
var config = {
source: '/dev/AlphaHelp/helpfiles',
generated: '/dev/AlphaHelp/generated',
ignoreItems: ['images', 'Orphans'] ,
search : {
provider: "elasticsearch"
}
};
var help = Help(config);
help.generate(function (err, result) {
if (err)
console.log("Error: " + err);
else
console.log('Help generated ' + result);
});
Populate a locally running elastic search instance with plaintext from all the files (requires a generate)
var Help = require('helpserver');
var config = {
source: '/dev/AlphaHelp/helpfiles',
generated: '/dev/AlphaHelp/generated',
ignoreItems: ['images', 'Orphans'] ,
search : {
provider: "elasticsearch"
}
};
var help = Help(config);
help.buildindex(function (err, result) {
if(err)
console.log( err );
else
console.log('Index built ' + JSON.stringify(result,null," "));
});
Once an index exists, perform a query (fulltext search with greater weight given to match of a topic title)
var Help = require('helpserver');
var config = {
source: '/dev/AlphaHelp/helpfiles',
generated: '/dev/AlphaHelp/generated',
ignoreItems: ['images', 'Orphans'] ,
search : {
provider: "elasticsearch"
}
};
var help = Help(config);
help.search('for_each',function(err,result) {
if(err) {
console.log(err);
} else {
console.log(JSON.stringify(result));
}
});
For out examples, we are placing the configuration for the help server in a json file we will call settings.json.
The settings file properties are set
{
"port": 80,
"metadata" : true ,
"dependencies" : true ,
"source": "/myhelp/helpfiles/",
"generated": "/myhelp/generated/",
"ignoreItems": [ "images" , "css" ],
"search": {
"provider": "elasticsearch"
} ,
"useGit": true,
"repoSource": "/myhelp/helpfiles" ,
"webhookPort" : 9001 ,
"webhookPath" : "/" ,
"webhookSecret" : "mywebhooksecretcode" ,
"configurations" : {
"novice" : {
"filter_name" : "novice" ,
"filter" : { "metadata.tags" : "easy" }
} ,
"expert" : {
"filter_name" : "expert" ,
"filter" : { "metadata.tags" : "easy,expert" }
},
"admin" : {
"isAdmin" : true
}
}
}
An express server with hooks for resolving pages, performing searchs, pulling the table of contents. In the following example, the main page is /main (i.e. "127.0.0.1/main" on your local machine).
source (/myhelp/helpfiles/) is the root of the static html files stored in a folder structure. generated (/myhelp/generated/) is where helpserver puts any generated html content (like the table of contents).
var express = require('express');
var app = express();
var options = require("./settings");
var Help = require('helpserver');
var help = Help(options);
app.use("/",function (req, res) {
help.expressuse(req, res);
});
app.listen(options.port);
console.log('Listening on port '+options.port);
A script to initialize Elastic Search index, this must be done before the the help server can be used, and depending on the size of your help system, this might take a while.
var express = require('express');
var app = express();
var options = require("./settings");
var Help = require('helpserver');
var help = Help(options);
// First build the table of contents
help.status(function (stats) {
if (options.search && !stats.indexServiceRunning) {
console.log('Cannot initialize indexes without '+options.search.provider+' instance running.');
} else {
help.generate(function (err, result) {
if (err)
console.log("Error: " + err);
else {
console.log('Help generated');
// Then build the index
help.buildindex(function (err, result) {
if (err)
console.log(err);
else
console.log('Indexes built ' + JSON.stringify(result, null, " "));
});
}
});
}
});
FAQs
Help system serving and for static html and markdown files.
The npm package helpserver receives a total of 0 weekly downloads. As such, helpserver popularity was classified as not popular.
We found that helpserver demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.