hdoc-tools 0.8.13 → 0.8.15

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,9 +3,7 @@
 
     const {
         createHash
-    } = require('crypto'), {
-            lutimesSync
-        } = require('fs'),
+    } = require('crypto'),
         dree = require('dree'),
         fs = require('fs-extra'),
         mdfm = require('markdown-it-front-matter'),
@@ -27,22 +25,27 @@
             'doc_content',
             'doc_preview UNINDEXED',
             'doc_family_id'
-        ];
+        ],
+        doc_header_template_path = path.join(__dirname, 'templates', 'doc-header.html');
 
-    let conversion_attempted = 0,
+    let bc = {}, // Breadcrumbs map
+        book_read_time = 0,
+        built_file_hashes = [],
+        conversion_attempted = 0,
         conversion_success = 0,
         conversion_failed = 0,
+        doc_header_template = '',
+        doc_id = '',
+        git_token = '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', // Github fine-grained personal access token that has minimum read-only access to Hornbill Docs org repo content
+        hdocbook_config = {},
+        hdocbook_project,
         includes_found = 0,
         includes_success = 0,
         includes_failed = 0,
-        book_read_time = 0,
-        hdocbook_project,
-        docId = '',
+        index_records = [],
         md_files = [],
         static_html_files = [],
-        index_records = [],
-        work_path_content = '',
-        built_file_hashes = [];
+        work_path_content = '';
 
     const transform_static_html = function (file_path) {
         if (fs.existsSync(file_path.path)) {
@@ -205,7 +208,9 @@
             let fm_content = frontmatter_content.split(/\r?\n/);
 
             let fm_contains_title = false,
-                fm_contains_reading_time = false;
+                fm_contains_reading_time = false,
+                doc_title = '',
+                doc_type = 'Article';
 
             if (fm_content.length >= 0) {
                 fm_content.forEach(function (fm_prop) {
@@ -218,6 +223,11 @@
 
                         if (fm_property[0].trim() === 'title') {
                             fm_contains_title = true;
+                            doc_title = fm_property[1].trim();
+                        }
+                        if (fm_property[0].trim() === 'type') {
+                            fm_contains_type = true;
+                            doc_type = fm_property[1].trim();
                         }
                         if (fm_property[0].trim() === 'reading-time') {
                             book_read_time += parseInt(fm_property[1].trim(), 10);
@@ -227,6 +237,12 @@
                 });
             }
 
+            // Add doc type
+            fm_headers.push({
+                id: 'type',
+                value: doc_type
+            });
+
             // 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
@@ -238,12 +254,16 @@
                         id: 'title',
                         value: html_heading[0].children[0].data.trim()
                     });
+                    doc_title = 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}`);
                 }
             }
 
+            // Remove the first <h1>title</h1> from the HTML as we'll ass that in the document header
+            html_txt = html_txt.replace(/(<h1.*?>)\s*.*\s*(.*<\/h1>)/, '');
+
             // Does frontmatter tag contain a reading-time property
             if (!fm_contains_reading_time) {
                 const read_time_mins = hdoc.get_html_read_time(html_txt);
@@ -254,15 +274,51 @@
                 });
             }
 
-            // Add frontmatter tags as comment to front of HTML 
+            // Get contributor data from Github, if exists
+            if (hdocbook_config.publicSource && hdocbook_config.publicSource !== '') {
+                const github_paths = hdoc.get_github_api_path(hdocbook_config.publicSource, file_path.relativePath);
+                const contributors = hdoc.get_github_contributors(github_paths.api_path, git_token);
+                if (!contributors.success) {
+                    console.log(`Error retrieving contributors from Github: ${contributors.error}`);
+                } else {
+                    fm_headers.push({
+                        id: 'contributor-count',
+                        value: contributors.contributor_count
+                    });
+                    fm_headers.push({
+                        id: 'last-commit',
+                        value: contributors.last_commit_date
+                    });
+                }
+                fm_headers.push({
+                    id: 'edit-path',
+                    value: github_paths.edit_path
+                });
+                const target_file = file_path.path.replace(path.extname(file_path.path), '._info.json');
+                delete contributors.success;
+                delete contributors.error;
+                contributors.editPath = github_paths.edit_path;
+                try {
+                    fs.writeFileSync(target_file, JSON.stringify(contributors, null, 2));
+                } catch (err) {
+                    console.log('Error writing:', target_file, '\n', err);
+                }
+            }
+
+            // Build doc header from template and frontmatter tags
+            const doc_header = process_doc_header(fm_headers, file_path.relativePath);
+
+            // Add frontmatter tags as comment to front of HTML
+
+            let fm_header = '<!--[[FRONTMATTER\n';
             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}`;
             }
+            fm_header += ']]-->';
+
+            html_txt = `${fm_header}\n${doc_header}\n${html_txt}`;
 
             // Save HTML into HTML file
             const target_file = file_path.path.replace(path.extname(file_path.path), '.html');
@@ -292,6 +348,46 @@
         return false;
     };
 
+    const process_doc_header = function (fm_headers, doc_path) {
+        let wip_doc_header = doc_header_template;
+
+        // Process fm_headers properties first
+        for (let i = 0; i < fm_headers.length; i++) {
+            switch (fm_headers[i].id) {
+                case 'title':
+                    wip_doc_header = wip_doc_header.replaceAll('{{title}}', fm_headers[i].value);
+                    break;
+                case 'reading-time':
+                    wip_doc_header = wip_doc_header.replaceAll('{{reading-time}}', fm_headers[i].value);
+                    break;
+                case 'contributor-count':
+                    wip_doc_header = wip_doc_header.replaceAll('{{contributor-count}}', fm_headers[i].value);
+                    break;
+                case 'type':
+                    wip_doc_header = wip_doc_header.replaceAll('{{doc-type}}', fm_headers[i].value);
+                    break;
+                case 'edit-path':
+                    wip_doc_header = wip_doc_header.replaceAll('{{edit-url}}', fm_headers[i].value);
+                    break;
+                case 'last-commit':
+                    const last_commit_date = new Date(fm_headers[i].value).toDateString();
+                    wip_doc_header = wip_doc_header.replaceAll('{{last-update}}', last_commit_date);
+                    break;
+            }
+        }
+
+        // Now sort out breadcrumbs
+        const logical_path = doc_path.replace(path.extname(doc_path), '');
+        const bc_for_path = bc[logical_path];
+        let bc_tags = '\n';
+        for (let i = 0; i < bc_for_path.length - 1; i++) {
+            bc_tags += `\t\t\t\t<li class="mt-0 nav-bar-item"><a href="${bc_for_path[i].link}" class="ps-0 pe-0 text-decoration-none">${bc_for_path[i].text}</a></li>\n`;
+        }
+        bc_tags += '\t\t\t';
+        wip_doc_header = wip_doc_header.replaceAll('{{breadcrumbs}}', bc_tags);
+        return wip_doc_header;
+    };
+
     // File callback for build scan
     const build_file_callback = function (element) {
         if (element.extension === 'md') {
@@ -330,7 +426,114 @@
         sorted: true
     };
 
-    exports.run = function (source_path, verbose) {
+    const build_breadcrumbs = function (nav_items) {
+        console.log('Processing navigation breadcrumbs...\n');
+        // Steve - need to rework this to use recursion, as it's hard-coded for a maximum of 4 levels deep right now
+        for (let a = 0; a < nav_items.length; a++) {
+            const nav_a = nav_items[a];
+            const parent_a = nav_a.text;
+            if (nav_a.link) {
+                if (nav_a.link.includes('\\')) {
+                    console.log(`Navigation items should not contain backslashes: ${nav_a.link}`);
+                    process.exit(1);
+                }
+                bc[nav_a.link] = [{
+                    text: nav_a.text,
+                    link: nav_a.link
+                }];
+            }
+            if (nav_a.items) {
+                for (let b = 0; b < nav_a.items.length; b++) {
+                    const nav_b = nav_a.items[b];
+                    const parent_b = nav_b.text;
+                    if (nav_b.link) {
+                        if (nav_b.link.includes('\\')) {
+                            console.log(`Navigation items should not contain backslashes: ${nav_b.link}`);
+                            process.exit(1);
+                        }
+                        if (bc[nav_a.link]) {
+                            bc[nav_b.link] = bc[nav_a.link];
+                        } else {
+                            bc[nav_b.link] = [{
+                                text: parent_a,
+                                link: nav_a.items[0].link
+                            }];
+                        }
+                        bc[nav_b.link].push({
+                            text: nav_b.text,
+                            link: nav_b.link
+                        });
+                    }
+
+                    if (nav_b.items) {
+                        for (let c = 0; c < nav_b.items.length; c++) {
+                            const nav_c = nav_b.items[c];
+                            const parent_c = nav_c.text;
+                            if (nav_c.link) {
+                                if (nav_c.link.includes('\\')) {
+                                    console.log(`Navigation items should not contain backslashes: ${nav_c.link}`);
+                                    process.exit(1);
+                                }
+                                if (bc[nav_b.link]) {
+                                    bc[nav_c.link] = bc[nav_b.link];
+                                } else {
+                                    bc[nav_c.link] = [{
+                                        text: parent_a,
+                                        link: nav_a.items[0].link
+                                    }];
+                                    bc[nav_c.link].push({
+                                        text: parent_b,
+                                        link: nav_b.items[0].link
+                                    });
+                                }
+                                bc[nav_c.link].push({
+                                    text: nav_c.text,
+                                    link: nav_c.link
+                                });
+                            }
+
+                            if (nav_c.items) {
+                                for (let d = 0; d < nav_c.items.length; d++) {
+                                    const nav_d = nav_c.items[d];
+                                    if (nav_d.link) {
+                                        if (bc[nav_c.link]) {
+                                            bc[nav_d.link] = bc[nav_c.link];
+                                        } else {
+                                            bc[nav_d.link] = [{
+                                                text: parent_a,
+                                                link: nav_a.items[0].link
+                                            }];
+                                            bc[nav_d.link].push({
+                                                text: parent_b,
+                                                link: nav_b.items[0].link
+                                            });
+                                            bc[nav_d.link].push({
+                                                text: parent_c,
+                                                link: nav_c.items[0].link
+                                            });
+                                        }
+                                        bc[nav_d.link].push({
+                                            text: nav_d.text,
+                                            link: nav_d.link
+                                        });
+                                    }
+                                }
+        
+                            }
+                        }
+                    }
+                }
+            }
+
+        }
+        //console.log(JSON.stringify(bc, null, 2));
+    };
+
+    exports.run = function (source_path, verbose, github_api_token) {
+        if (github_api_token !== '') {
+            git_token = github_api_token;
+        }
+            
         // GERRY: The purpose of this function is to create a zip file containing the hdocbook content, 
         // * Create a _work folder 
         // * copy the hdocbook content to the work folder
@@ -348,20 +551,19 @@
         // use the docId to get the book config
         const hdocbook_project_config_path = path.join(source_path, 'hdocbook-project.json');
         hdocbook_project = require(hdocbook_project_config_path);
+        doc_id = hdocbook_project.docId;
 
-        docId = hdocbook_project.docId;
-
-        const book_path = path.join(source_path, docId),
+        const book_path = path.join(source_path, doc_id),
             hdocbook_path = path.join(book_path, 'hdocbook.json'),
-            hdocbook_config = require(hdocbook_path),
             work_path = path.join(source_path, '_work'),
-            work_hdocbook_path = path.join(work_path, docId, 'hdocbook.json');
+            work_hdocbook_path = path.join(work_path, doc_id, 'hdocbook.json');
 
-        console.log(`Building: ${docId} v${hdocbook_config.version}...\n`);
+        hdocbook_config = require(hdocbook_path);
+
+        console.log(`Building: ${doc_id} v${hdocbook_config.version}...\n`);
 
-        
-        work_path_content = path.join(work_path, docId);
         // Make _work folder to copy everything into
+        work_path_content = path.join(work_path, doc_id);
         if (fs.existsSync(work_path)) {
             fs.rmSync(work_path, {
                 recursive: true,
@@ -370,14 +572,24 @@
         }
         fs.mkdirSync(work_path);
 
-        // Copy files from book into _work-docId folder
+        // Copy files from book into _work-doc_id folder
         try {
-            fs.copySync(path.join(source_path, docId), work_path_content);
+            fs.copySync(path.join(source_path, doc_id), work_path_content);
         } catch (e) {
             console.error('Error copying from source_path:\n', e);
             process.exit(1);
         }
 
+        // Load document header template
+        try {
+            doc_header_template = fs.readFileSync(doc_header_template_path, 'utf8');
+        } catch (err) {
+            console.log(`Error reading document header template: ${err}`);
+            process.exit(1);
+        }
+
+        build_breadcrumbs(hdocbook_config.navigation.items);
+
         // Get a list of MD files in work_path
         dree.scan(work_path, dreeOptions, build_file_callback);
 
@@ -391,25 +603,23 @@
             transform_static_html(static_html_file);
         });
 
-
         console.log(`                MD files found: ${conversion_attempted}`);
         console.log(`Successfully converted to HTML: ${conversion_success}`);
         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}\n`);
-
         console.log(`       Static HTML Files Found: ${static_html_files.length}\n`);
 
         // Validate content
-        const validation_success = validate.run(work_path, docId, verbose);
+        const validation_success = validate.run(work_path, doc_id, verbose);
         if (!validation_success) {
             process.exit(1);
         }
 
         // Now build the index
         console.log('Performing SQlite index creation...');
-        let db_name = path.join(work_path, docId, 'index.db');
+        let db_name = path.join(work_path, doc_id, 'index.db');
         const db = new Database(db_name);
         db.pragma('encoding="UTF-8"');
         console.log(`\nDatabase created: ${db_name}`);
@@ -425,11 +635,11 @@
             if (!hdocbook_config.tags) hdocbook_config.tags = [];
             let index_success_count = 0;
             for (let i = 0; i < index_records.length; i++) {
-                let index_path_name = index_records[i].relative_path.replace('\\', '/').replace(`${hdocbook_config.docId}/`, '');
+                let index_path_name = index_records[i].relative_path.replace('\\', '/').replace(`${doc_id}/`, '');
                 index_path_name = index_path_name.replace(path.extname(index_records[i].relative_path), '');
                 const index_vals = [
                     index_path_name,
-                    hdocbook_config.docId,
+                    doc_id,
                     hdocbook_config.audience.join(','),
                     hdocbook_config.tags.join(','),
                     index_records[i].index_html.fm_props.title,
@@ -437,14 +647,14 @@
                     index_records[i].index_html.preview,
                     hdocbook_config.productFamily
                 ];
-                const index_response = hdoc_index.insert_record(db, table_name, index_cols, index_vals, hdocbook_config.docId, index_records[i].index_html.fm_props.title);
+                const index_response = hdoc_index.insert_record(db, table_name, index_cols, index_vals, doc_id, index_records[i].index_html.fm_props.title);
                 if (!index_response.success) {
-                    console.log(`Index record creation failed - ${hdocbook_config.docId}/${index_records[i].index_html.fm_props.title}: ${index_response.error}`);
+                    console.log(`Index record creation failed - ${doc_id}/${index_records[i].index_html.fm_props.title}: ${index_response.error}`);
                     continue;
                 }
                 index_success_count++;
                 if (verbose) {
-                    console.log(`Inserted index record ${index_response.row_id}: ${hdocbook_config.docId} - ${index_records[i].index_html.fm_props.title}`);
+                    console.log(`Inserted index record ${index_response.row_id}: ${doc_id} - ${index_records[i].index_html.fm_props.title}`);
                 }
             }
             console.log(`\nIndex Build Complete: ${index_success_count} records created.`);
@@ -483,7 +693,7 @@
         }
 
         try {
-            const zip_path = path.join(work_path, docId + '.zip');
+            const zip_path = path.join(work_path, doc_id + '.zip');
             zipper.sync.zip(work_path_content).compress().save(zip_path);
             console.log(`\nZIP Creation Success: ${zip_path}\n`);
             console.log('Build Complete\n');

package/hdoc-module.js

@@ -213,4 +213,73 @@
         if (read_time === 0) read_time = 1;
         return read_time;
     };
+
+    exports.get_github_api_path = function(repo, relative_path) {
+        repo = repo.endsWith('/') ? repo.slice(0, -1) : repo;
+        let github_paths = {};
+        github_paths.api_path = repo.replace('https://github.com/', 'https://api.github.com/repos/');
+        github_paths.api_path += '/commits?path=/' + relative_path.replace('\\\\', '/').replace('\\', '/');
+        github_paths.edit_path = repo + '/blob/main/' + relative_path.replace('\\\\', '/').replace('\\', '/');
+        return github_paths;
+    };
+
+    exports.get_github_contributors = function(github_url, github_api_token) {
+        let response = {
+            success: false,
+            error: '',
+            contributors: [],
+            contributor_count: 0,
+            last_commit_date:''
+        };
+
+        let contributors = {};
+
+        let request_options = {
+            headers: {
+                'User-Agent': 'HornbillDocsBuild',
+                'Cache-Control': 'no-cache',
+                'Host': 'api.github.com',
+                'Accept': 'application/json'
+            }
+        };
+        if (github_api_token !== '') {
+            request_options.headers.authorization = `Bearer ${github_api_token}`;
+        }
+        const github_response = request('GET', github_url, request_options);
+
+        if (github_response.statusCode === 200) {
+            response.success = true;
+            let commits = github_response.getBody('UTF8');
+            commits = JSON.parse(commits);
+            commits.forEach(function(commit){
+                if (commit.committer.type.toLowerCase() === 'user' && commit.committer.login.toLowerCase() !== 'web-flow') {
+                    if (!contributors[commit.committer.id]) {
+                        response.contributor_count++;
+                        contributors[commit.committer.id] = {
+                            login: commit.committer.login,
+                            avatar_url: commit.committer.avatar_url,
+                            html_url: commit.committer.html_url,
+                            name: commit.commit.committer.name
+                        };
+                    }
+                    if (response.last_commit_date !== '') {
+                        const new_commit_date = new Date(commit.commit.committer.date);
+                        const exist_commit_date = new Date(response.last_commit_date);
+                        if (new_commit_date > exist_commit_date) response.last_commit_date = commit.commit.committer.date;
+                    } else {
+                        response.last_commit_date = commit.commit.committer.date;
+                    }
+                }
+            });
+            for (const key in contributors) {
+                if (contributors.hasOwnProperty(key)) {
+                    response.contributors.push(contributors[key]);
+                }
+            }
+        } else {
+            response.error = `Unexpected Status ${github_response.statusCode}. ${JSON.parse(github_response.body.toString('utf8')).message}`;
+        }
+        return response;
+    };
+
 })();

package/hdoc.js

@@ -25,7 +25,7 @@
    // Default source path to working directory
    let source_path = process.cwd();
    let ui_path = path.join(__dirname, 'ui');
-
+   let git_token = '';
    let command = '', // Our command to run
       verbose = false;
 
@@ -50,6 +50,11 @@
          if (x < process.argv.length) {
             ui_path = process.argv[x];
          }
+      } else if (process.argv[x] == '-git-token') {
+         x++;
+         if (x < process.argv.length) {
+            git_token = process.argv[x];
+         }
       }
 
       if (process.argv[x] === '-v') {
@@ -66,7 +71,7 @@
       server.run(ui_path, source_path);
    } else if (command == 'build') {
       const builder = require(path.join(__dirname, 'hdoc-build.js'));
-      builder.run(source_path, verbose);
+      builder.run(source_path, verbose, git_token);
    } else if (command == 'stats') {
       const stats = require(path.join(__dirname, 'hdoc-stats.js'));
       stats.run(ui_path, source_path, verbose);

package/package.json

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

package/templates/doc-header.html

@@ -0,0 +1,30 @@
+<div class="document-header">
+    <div class="hb-container-horizontal">
+        <div class="hb-center-v hb-container-expand">
+            <ul class="ps-0 nav-bar-nav-list noeffects after-fslash overflow-ellipsis">{{breadcrumbs}}</ul>
+        </div> 
+        <div class="toolbar-right hb-center-v">
+            <a target="_blank" class="toolbar-action" href="{{edit-url}}">
+                <i class="bi bi-pencil"></i>
+            </a> 
+            <a class="toolbar-action documentation-menu-popper">
+                <i class="bi bi-three-dots-vertical"></i>
+            </a>
+        </div>
+    </div> 
+    
+    <h1>{{title}}</h1>
+    
+    <div class="hb-container-horizontal">
+        <div class="hb-center-v hb-container-expand">
+            <ul class="ps-0 nav-bar-nav-list noeffects after-bullets overflow-ellipsis text-light-2">
+                <li class="ps-0 mt-0 nav-bar-item">{{doc-type}}</li>
+                <li class="ps-0 mt-0 nav-bar-item">{{last-update}}</li>
+                <li class="ps-0 mt-0 nav-bar-item">{{reading-time}} minutes to read</li> 
+                <li class="ps-0 mt-0 nav-bar-item">
+                    <a class="link c-pointer" data-bs-toggle="modal" data-bs-target="#contributersModal">{{contributor-count}} contributors</a>
+                </li>
+            </ul>
+        </div> 
+    </div>
+</div>

package/ui/css/theme-default/styles/base.css

@@ -112,7 +112,7 @@ samp {
 
 img,
 svg {
-  display: inline;
+  display: inline-block;
 }
 
 video,