hdoc-tools 0.8.10 → 0.8.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Hornbill Docs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/hdoc-build.js

@@ -3,7 +3,9 @@
 
     const {
         createHash
-    } = require('crypto'),
+    } = require('crypto'), {
+            lutimesSync
+        } = require('fs'),
         dree = require('dree'),
         fs = require('fs-extra'),
         mdfm = require('markdown-it-front-matter'),
@@ -33,13 +35,13 @@
         includes_found = 0,
         includes_success = 0,
         includes_failed = 0,
+        book_read_time = 0,
         hdocbook_project,
         docId = '',
         md_files = [],
         static_html_files = [],
         index_records = [],
         work_path_content = '',
-        built_relative_paths = [],
         built_file_hashes = [];
 
     const transform_static_html = function (file_path) {
@@ -50,16 +52,20 @@
 
             let html_txt_updated = false;
 
+            let fm_headers = [];
+            let existing_fm_headers = false;
+
             // Check if we have a frontmatter comment
             const fm_header = hdoc.getHTMLFrontmatterHeader(html_txt);
             if (Object.keys(fm_header.fm_properties).length > 0) {
+                existing_fm_headers = true;
+
                 // We have some frontmatter headers, check if title is one of them
                 let fm_title_found = false;
                 if (fm_header.fm_properties && fm_header.fm_properties.title !== undefined) {
                     // We have a title - but does the title have a value
                     if (fm_header.fm_properties.title === '') {
-                        // No value - remove title from the properties map 
-                        // so we don't end up with 2 title properties, one empty and one with a value
+                        // No value - remove title from the properties map  so we don't end up with 2 title properties, one empty and one with a value
                         delete fm_header.fm_properties.title;
                     } else {
                         // We have a value for the title property
@@ -67,6 +73,22 @@
                     }
                 }
 
+                // Is reading-time in the fm headers?
+                if (fm_header.fm_properties['reading-time'] === undefined) {
+                    const read_time_mins = hdoc.get_html_read_time(html_txt);
+                    book_read_time += read_time_mins;
+                    fm_header.fm_properties['reading-time'] = read_time_mins;
+                }
+
+                for (const key in fm_header.fm_properties) {
+                    if (fm_header.fm_properties.hasOwnProperty(key)) {
+                        fm_headers.push({
+                            id: key,
+                            value: fm_header.fm_properties[key]
+                        });
+                    }
+                }
+
                 if (!fm_title_found) {
                     // No frontmatter title found in properties
                     // Go get title from h tags in html
@@ -74,15 +96,10 @@
 
                     if (html_heading && html_heading[0] && html_heading[0].children && html_heading[0].children[0] && html_heading[0].children[0].data) {
                         // We've found a heading tag, add that as a title to the existing frontmatter properties
-                        let frontmatter_header = `[[FRONTMATTER\ntitle: ${html_heading[0].children[0].data}`;
-                        for (const key in fm_header.fm_properties) {
-                            if (fm_header.fm_properties.hasOwnProperty(key)) {
-                                frontmatter_header += `\n${key}: ${fm_header.fm_properties[key]}`;
-                            }
-                        }
-                        frontmatter_header += '\n]]';
-                        html_txt = html_txt.replace(fm_header.fm_header, frontmatter_header);
-                        html_txt_updated = true;
+                        fm_headers.push({
+                            id: 'title',
+                            value: html_heading[0].children[0].data
+                        });
                     } else {
                         // No header tag, no frontmatter title, output a warning 
                         console.log(`No frontmatter title property, or ${h_tags_to_search.join(', ')} tags detected in ${file_path.path}`);
@@ -91,16 +108,44 @@
             } else {
                 // We have no frontmatter headers, get and build one from the html headings
                 const html_heading = hdoc.getFirstHTMLHeading(html_txt, h_tags_to_search);
+
+                // Add the title
                 if (html_heading && html_heading[0] && html_heading[0].children && html_heading[0].children[0] && html_heading[0].children[0].data) {
                     // We've found a heading tag, add that as a title to the frontmatter content
-                    const frontmatter_header = `<!--[[FRONTMATTER\r\ntitle: ${html_heading[0].children[0].data}\r\n]]-->\r\n`;
-                    html_txt = frontmatter_header + html_txt;
-                    html_txt_updated = true;
+                    fm_headers.push({
+                        id: 'title',
+                        value: html_heading[0].children[0].data
+                    });
                 } else {
                     // No header tag, no frontmatter title, output a warning 
                     console.log(`No frontmatter title property, or ${h_tags_to_search.join(', ')} tags detected in ${file_path.path}`);
                 }
+
+                // Add the reading time
+                const read_time_mins = hdoc.get_html_read_time(html_txt);
+                book_read_time += read_time_mins;
+                fm_headers.push({
+                    id: 'reading-time',
+                    value: read_time_mins
+                });
+            }
+
+            if (fm_headers.length > 0) {
+                let fm_headers_content = '[[FRONTMATTER\n';
+                for (let i = 0; i < fm_headers.length; i++) {
+                    fm_headers_content += `${fm_headers[i].id}: ${fm_headers[i].value}\n`;
+                }
+                fm_headers_content += ']]';
+
+                if (existing_fm_headers) {
+                    html_txt = html_txt.replace(fm_header.fm_header, fm_headers_content);
+                    html_txt_updated = true;
+                } else {
+                    html_txt = `<!--${fm_headers_content}-->\n${html_txt}`;
+                    html_txt_updated = true;
+                }
             }
+
             index_records.push({
                 relative_path: file_path.relativePath,
                 index_html: hdoc_index.transform_html_for_index(html_txt)
@@ -108,7 +153,7 @@
             if (html_txt_updated) {
                 // Save HTML into HTML file
                 fs.writeFile(file_path.path, html_txt, function writeJSON(err) {
-                    if (err) return console.log('Error writing:', target_file, '\r\n', err);
+                    if (err) return console.log('Error writing:', target_file, '\n', err);
                 });
             }
         }
@@ -155,40 +200,75 @@
             // Render markdown into HTML
             let html_txt = md.render(md_txt.toString());
 
-            // Does frontmatter tag contain a title property
-            let fm_contains_title = false;
+            // Prepare frontmatter headers
+            let fm_headers = [];
             let fm_content = frontmatter_content.split(/\r?\n/);
+
+            let fm_contains_title = false,
+                fm_contains_reading_time = false;
+
             if (fm_content.length >= 0) {
                 fm_content.forEach(function (fm_prop) {
                     const fm_property = fm_prop.split(':');
-                    if (fm_property[0] && fm_property[0] === 'title' && fm_property[1] && fm_property[1].length > 0) fm_contains_title = true;
+                    if (fm_property[0] && fm_property[0].trim().length > 0 && fm_property[1] && fm_property[1].trim().length > 0) {
+                        fm_headers.push({
+                            id: fm_property[0].trim(),
+                            value: fm_property[1].trim()
+                        });
+
+                        if (fm_property[0].trim() === 'title') {
+                            fm_contains_title = true;
+                        }
+                        if (fm_property[0].trim() === 'reading-time') {
+                            book_read_time += parseInt(fm_property[1].trim(), 10);
+                            fm_contains_reading_time = true;
+                        }
+                    }
                 });
             }
 
+            // Does frontmatter tag contain a title property
             if (!fm_contains_title) {
                 // Frontmatter tags don't contain a title property - go pull the first one from the html heading tags
                 const html_heading = hdoc.getFirstHTMLHeading(html_txt, h_tags_to_search);
 
                 if (html_heading && html_heading[0] && html_heading[0].children && html_heading[0].children[0] && html_heading[0].children[0].data) {
                     // We've found a heading tag, add that as a title to the frontmatter content
-                    if (frontmatter_content.length > 0) frontmatter_content += '\r\n';
-                    frontmatter_content += `title: ${html_heading[0].children[0].data}`;
+                    fm_headers.push({
+                        id: 'title',
+                        value: html_heading[0].children[0].data.trim()
+                    });
                 } else {
                     // No header tag, no frontmatter title, output a warning 
                     console.log(`No frontmatter title property, or h1, h2 or h3 header tags detected in ${file_path}`);
                 }
             }
 
+            // Does frontmatter tag contain a reading-time property
+            if (!fm_contains_reading_time) {
+                const read_time_mins = hdoc.get_html_read_time(html_txt);
+                book_read_time += read_time_mins;
+                fm_headers.push({
+                    id: 'reading-time',
+                    value: read_time_mins
+                });
+            }
+
             // Add frontmatter tags as comment to front of HTML 
-            if (frontmatter_content.length) {
-                html_txt = "<!--[[FRONTMATTER\r\n" + frontmatter_content + "\r\n]]-->\r\n" + html_txt;
+            if (fm_headers.length > 0) {
+                let fm_header = '<!--[[FRONTMATTER\n';
+                for (let i = 0; i < fm_headers.length; i++) {
+                    fm_header += `${fm_headers[i].id}: ${fm_headers[i].value}\n`;
+                }
+                fm_header += ']]-->';
+                html_txt = `${fm_header}\n${html_txt}`;
             }
 
             // Save HTML into HTML file
             const target_file = file_path.path.replace(path.extname(file_path.path), '.html');
             const relative_path = file_path.relativePath.replace(path.extname(file_path.path), '.html');
             fs.writeFile(target_file, html_txt, function writeJSON(err) {
-                if (err) return console.log('Error writing:', target_file, '\r\n', err);
+                if (err) return console.log('Error writing:', target_file, '\n', err);
             });
 
             const index_details = hdoc_index.transform_html_for_index(html_txt);
@@ -218,12 +298,8 @@
             md_files.push(element);
         } else {
             // File is html, see if there's a matching md file and if there is then ignore the html
-            let html_path = element.path.replace(path.extname(element.path), '.html');
-            if (fs.existsSync(html_path)) {
-                return;
-            }
-            html_path = element.path.replace(path.extname(element.path), '.htm');
-            if (fs.existsSync(html_path)) {
+            const md_path = element.path.replace(path.extname(element.path), '.md');
+            if (fs.existsSync(md_path)) {
                 return;
             }
             static_html_files.push(element);
@@ -265,8 +341,8 @@
         //   within the book. 
         // * Package everything up into a ZIP file, ready for the build controller to package and publish
 
-        console.log('Hornbill HDocBook Build', '\r\n');
-        console.log('  Document Path:', source_path, '\r\n');
+        console.log('Hornbill HDocBook Build', '\n');
+        console.log('  Document Path:', source_path, '\n');
 
         // Load the hdocbook-project.json file to get the docId
         // use the docId to get the book config
@@ -277,11 +353,13 @@
 
         const book_path = path.join(source_path, docId),
             hdocbook_path = path.join(book_path, 'hdocbook.json'),
-            hdocbook_config = require(hdocbook_path);
+            hdocbook_config = require(hdocbook_path),
+            work_path = path.join(source_path, '_work'),
+            work_hdocbook_path = path.join(work_path, docId, 'hdocbook.json');
 
-        console.log(`Building: ${docId} v${hdocbook_config.version}...\r\n`);
+        console.log(`Building: ${docId} v${hdocbook_config.version}...\n`);
 
-        const work_path = path.join(source_path, '_work');
+        
         work_path_content = path.join(work_path, docId);
         // Make _work folder to copy everything into
         if (fs.existsSync(work_path)) {
@@ -296,7 +374,7 @@
         try {
             fs.copySync(path.join(source_path, docId), work_path_content);
         } catch (e) {
-            console.error('Error copying from source_path:\r\n', e);
+            console.error('Error copying from source_path:\n', e);
             process.exit(1);
         }
 
@@ -316,12 +394,12 @@
 
         console.log(`                MD files found: ${conversion_attempted}`);
         console.log(`Successfully converted to HTML: ${conversion_success}`);
-        console.log(`             Failed to convert: ${conversion_failed}\r\n`);
+        console.log(`             Failed to convert: ${conversion_failed}\n`);
         console.log(`                Includes Found: ${includes_found}`);
         console.log(`              Includes Success: ${includes_success}`);
-        console.log(`               Includes Failed: ${includes_failed}\r\n`);
+        console.log(`               Includes Failed: ${includes_failed}\n`);
 
-        console.log(`       Static HTML Files Found: ${static_html_files.length}\r\n`);
+        console.log(`       Static HTML Files Found: ${static_html_files.length}\n`);
 
         // Validate content
         const validation_success = validate.run(work_path, docId, verbose);
@@ -394,6 +472,16 @@
         }
 
 
+        // Add book read timing to the hdocbook.json
+        hdocbook_config.readingTime = Math.ceil(book_read_time + ((book_read_time / 100) * 10));
+        try {
+            fs.writeFileSync(work_hdocbook_path, JSON.stringify(hdocbook_config, null, 2));
+            console.log('\nhdocbook.json update success:', work_hdocbook_path);
+        } catch (e) {
+            console.log('\nError creating', work_hdocbook_path, ':', e);
+            process.exit(1);
+        }
+
         try {
             const zip_path = path.join(work_path, docId + '.zip');
             zipper.sync.zip(work_path_content).compress().save(zip_path);

package/hdoc-init.js

@@ -89,7 +89,7 @@
             hdocbookFile.version = docProps.version;
             hdocbookFile.navigation.items[0].items = [{
                 "text": "Welcome",
-                "link": path.join(docProps.id, 'index')
+                "link": docProps.id + '/index'
             }];
             fs.writeFile(hdocBookFilePath, JSON.stringify(hdocbookFile, null, 2), function writeJSON(err) {
                 if (err) return console.log('Error updating:', hdocBookFilePath, '\r\n', err);

package/hdoc-module.js

@@ -2,7 +2,9 @@
     'use strict';
 
     const   cheerio = require('cheerio'),
-            request = require('sync-request');
+            request = require('sync-request'),
+            html2text = require('html-to-text'),
+            wordsCount = require('words-count').default;
 
     let includesCache = {};
 
@@ -196,5 +198,19 @@
         if (str.length <= n) { return str; }
         const subString = str.slice(0, n-1);
         return (useWordBoundary ? subString.slice(0, subString.lastIndexOf(" ")) : subString) + '…';
-      };
+    };
+
+    exports.get_html_read_time = function(html) {
+        // Get word count
+        const text = html2text.convert(html, {
+            wordwrap: null
+        });
+        const word_count = wordsCount(text);
+        if (word_count === 0) return 0;
+
+        // Calculate the read time - divide the word count by 200
+        let read_time = Math.round(word_count / 200);
+        if (read_time === 0) read_time = 1;
+        return read_time;
+    };
 })();

package/hdoc-stats.js

@@ -60,7 +60,7 @@
         symbolicLinks: false
     };
 
-    exports.run = function(ui_path, source_path, verbose = false) {
+    exports.run = function(ui_path, source_path, md, verbose = false) {
         
         // GERRY: The stats here are needed to support content development. The idea is to count all of the ]
         // words in a HDocBook so we know the size of the book, this helps with 3rd party involvement where
@@ -76,7 +76,7 @@
         // * MD files, and word count those
         
 
-        console.log('Hornbill HDocBook Stats : verbose=' + verbose, '\r\n');
+        console.log('Hornbill HDocBook Stats', '\r\n');
 
         const project_json_path = path.join(source_path, 'hdocbook-project.json');
 

package/hdoc.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 (function () {
    'use strict';
@@ -58,8 +58,6 @@
 
    }
 
-   console.log("VERBOSE: ", verbose);
-
    console.log('Hornbill HDocBook Tools v' + getHdocPackageVersion(packageFile), '\r\n');
    console.log('    Server Path:', __dirname);
    console.log('  Document Path:', source_path, '\r\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hdoc-tools",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "description": "Hornbill HDocBook Development Support Tool",
   "main": "hdoc.js",
   "bin": {

package/templates/init/resources/README.md

@@ -0,0 +1,3 @@
+You should store any files and resources that used in the creation of this hdocbook, but do not form part of the published content.
+
+These files are included in the build and final content output but we should keep in the source code repo for future revisions.  For example, if you were to create an image used in the content, say, in Photoshop, you will create the image and put that into the appropriate content location.  However, you may also want to put the Photoshop source file into this **resources** folder in order to keep for the future, should anyone need to modify the image, we have the original source file.