@bbc/morty-docs 1.12.2 → 3.0.1

package/README.md

@@ -88,6 +88,14 @@ through because it is not markdown or asciidoc e.g. images
 
 ## Things to Consider
 
+### Index file generation
+
+Morty will automatically generate an `index.html` file for any directory that
+contains markdown or asciidoc files (or has descendants that contain these
+files). This file contains links to any documentation files or subdirectories
+the directory contains. The generation will be skipped for any directory that
+already contains an `index.md`, `index.asciidoc`, `index.adoc` or `index.asc` file.
+
 ### File & Directory Ordering
 
 These are sorted lexically (0-9 < a-z>).
@@ -189,4 +197,4 @@ We would expect code quality to be at least as good if not better than
 the code quality of the project at the time you make your contribution.
 After all, we all hope to leave things better than we find them!
 
-© BBC 2021
+© BBC 2024

package/build/generate-indexes.js

@@ -1,13 +1,8 @@
 const path = require('path');
-
 const renderIndexPage = require('./page-renderers/IndexPage');
-
 const getDirectories = require('./helpers/get-directory-paths');
-
 const filterFilesInDirectory = require('./helpers/filter-files-in-dir');
-
 const filterDirectoriesInDirectory = require('./helpers/filter-dirs-in-dir');
-
 const generateIndex = (directory, filePaths, subDirPaths, options) => {
   const subDirLinks = subDirPaths.filter(dirPath => !dirPath.includes('/')).map(dirPath => ({
     link: `${dirPath}/index.html`,
@@ -24,22 +19,23 @@ const generateIndex = (directory, filePaths, subDirPaths, options) => {
   });
   return renderIndexPage([...subDirLinks, ...fileLinks], options, directory);
 };
-
 const generateIndexes = (files, options = {
   contentTitle: ''
 }) => {
   const supportedFilePaths = files.map(file => file.relativePath).filter(relativePath => path.extname(relativePath) === '.html' || path.extname(relativePath) === '.pdf');
-  const directories = getDirectories(supportedFilePaths); // If we have not got a 'root' folder, then add one.
+  const directories = getDirectories(supportedFilePaths);
+  // If we have not got a 'root' folder, then add one.
   // TODO: Refactor this so it is not needed (maybe?)
-
   if (!directories.includes('')) {
     directories.push('');
   }
-
-  const indexes = directories.map(directory => {
+  const indexes = directories.flatMap(directory => {
     const filesInDir = filterFilesInDirectory(supportedFilePaths, directory);
     const subDirsInDir = filterDirectoriesInDirectory(directories, directory);
-    const indexPath = directory ? `${directory}/index.html` : 'index.html';
+    const indexPath = path.join(directory, 'index.html');
+    if (filesInDir.includes(indexPath)) {
+      return [];
+    }
     return {
       relativePath: indexPath,
       raw: Buffer.from(generateIndex(directory, filesInDir, subDirsInDir, options))
@@ -47,5 +43,4 @@ const generateIndexes = (files, options = {
   });
   return indexes;
 };
-
 module.exports = generateIndexes;

package/build/generate-transform-input.js

@@ -1,19 +1,54 @@
-const readdir = require('recursive-readdir');
-
 const fs = require('fs');
-
 const path = require('path');
-
 const generateTransformInput = dir => {
   dir = path.format(path.parse(dir));
-  return readdir(dir).then(files => {
-    return files.map(file => {
-      return {
-        relativePath: file.toString().replace(`${dir}/`, ''),
-        raw: fs.readFileSync(file)
-      };
-    });
+  let list = [];
+  const files = fs.readdirSync(dir, {
+    recursive: true,
+    withFileTypes: true
   });
-};
+  // recursive option available from node 18+
+  // when options.withFileTypes set to true, the returned array will contain <fs.Dirent> objects.
+  for (const dirent of files) {
+    // Node API for Dirent is unstable
+    const dirPath = dirent.path || dirent.parentPath; // path is DEPRECATED! But parentPath does not work in 18.17
 
+    const fullPath = path.join(dirPath, dirent.name);
+    // console.log('fullPath = ', fullPath)
+
+    if (dirent.isDirectory()) {
+      console.log('directory... continue');
+      continue;
+    }
+    if (dirent.isFile()) {
+      list.push(makeInputObject(fullPath, dir));
+      continue;
+    }
+    if (dirent.isSymbolicLink) {
+      if (fs.existsSync(fullPath)) {
+        // fs.exists() is deprecated, but fs.existsSync() is not.
+        const stats = fs.statSync(fullPath);
+        console.log('Good symlink');
+        if (stats.isFile()) {
+          // get file details
+          list.push(makeInputObject(fullPath, dir)); // symlinks become copies
+        } else {
+          // recursive call to get all files in the symlinked directory
+          const newlist = generateTransformInput(fullPath);
+          list = list.concat(newlist);
+        }
+      } else {
+        console.log(`Broken symlink at: ${fullPath}`);
+      }
+      continue;
+    }
+  }
+  return list;
+};
+const makeInputObject = (fullPath, rootPath) => {
+  return {
+    relativePath: fullPath.replace(`${rootPath}/`, ''),
+    raw: fs.readFileSync(fullPath, 'utf-8')
+  };
+};
 module.exports = generateTransformInput;

package/build/helpers/filter-dirs-in-dir.js

@@ -1,24 +1,21 @@
 const {
   sortArrayByDate
 } = require('./sort-array-by-date');
-
 const filterDirs = (directoryPaths, directory) => {
   const directoryArray = [];
   const nestedDirFolders = directoryPaths.filter(directoryPath => directoryPath.includes(directory) && !directoryPath.startsWith(directory) && directoryPath !== directory);
-  if (nestedDirFolders.length) directoryArray.push(nestedDirFolders); // if directory path includes the config folder then return the full directory path
+  if (nestedDirFolders.length) directoryArray.push(nestedDirFolders);
+  // if directory path includes the config folder then return the full directory path
 
   const rootDirFolders = directoryPaths.filter(directoryPath => directoryPath.startsWith(directory) && directoryPath !== directory);
   const rootDir = rootDirFolders.map(directoryPath => directoryPath.startsWith(`${directory}/`) && directory !== '' ? directoryPath.replace(`${directory}/`, '') : directoryPath);
-  if (rootDir.length) directoryArray.push(rootDir); // if directory path starts with the config folder then remove the directory from the path
+  if (rootDir.length) directoryArray.push(rootDir);
+  // if directory path starts with the config folder then remove the directory from the path
   // sort array here
-
   let sortedDirectoryArray = directoryArray;
-
   if (sortedDirectoryArray.length) {
     sortedDirectoryArray.map(arr => sortArrayByDate(arr));
   }
-
   return sortedDirectoryArray.flat();
 };
-
 module.exports = filterDirs;

package/build/helpers/filter-files-in-dir.js

@@ -1,13 +1,9 @@
 const {
   sortArrayByDate
 } = require('./sort-array-by-date');
-
 const directoryDepth = path => path.split('/').length;
-
 const isInRootDirectory = filePath => directoryDepth(filePath) === 1;
-
 const isIn = directory => filePath => filePath.startsWith(directory) && directoryDepth(filePath) - 1 === directoryDepth(directory);
-
 module.exports = (filePaths, directory) => {
   const isInSpecifiedDirectory = directory ? isIn(directory) : isInRootDirectory;
   return sortArrayByDate(filePaths.filter(isInSpecifiedDirectory));

package/build/helpers/get-directory-paths.js

@@ -4,7 +4,6 @@ const getDirectoryPaths = filePaths => {
     if (!path.includes('/')) return ''; // if file is not in the directory, return '', as this is the root
 
     const splitPaths = path.split('/'); // => [ 'SomeOtherDir', 'AnotherDir', 'AnotherNestedDir', 'File1.html' ]
-
     splitPaths.pop(); // remove file.html
 
     const allDirs = splitPaths.map((splitPath, index) => {
@@ -15,14 +14,11 @@ const getDirectoryPaths = filePaths => {
   });
   return [...new Set(dirPaths.flat())];
 };
-
 const joinPathParts = (pathsArray, end) => {
   if (end === 0) {
     return pathsArray[0];
   }
-
   end++;
   return pathsArray.slice(0, end).join('/');
 };
-
 module.exports = getDirectoryPaths;

package/build/helpers/get-header-paths.js

@@ -11,5 +11,4 @@ const getHeaderLinks = (basePath, relPath = '') => {
     return acc;
   }, []);
 };
-
 module.exports = getHeaderLinks;

package/build/helpers/sort-array-by-date.js

@@ -3,11 +3,9 @@ const dateRegex = /\d{4}-\d{2}-\d{2}/; // i.e. 2019-10-29
 function sortByDate(a, b) {
   return a.match(dateRegex) && b.match(dateRegex) ? b.localeCompare(a) : a.localeCompare(b);
 }
-
 const sortArrayByDate = arr => {
   return arr.sort(sortByDate);
 };
-
 module.exports = {
   sortArrayByDate
 };

package/build/index.js

@@ -1,7 +1,5 @@
 const transform = require('./transform');
-
 const generateTransformInput = require('./generate-transform-input');
-
 module.exports = {
   transform,
   generateTransformInput

package/build/markdown-to-html-parser.js

@@ -1,14 +1,15 @@
-const showdown = require('showdown'); // there may be an option to enable this, but since we haven't found it here is a reg-ex
-// to convert links within a file from *.md to *.html
-
+const showdown = require('showdown');
 
+// there may be an option to enable this, but since we haven't found it here is a reg-ex
+// to convert links within a file from *.md to *.html
 const convertMdLinksToHtmlLinks = {
   type: 'output',
   regex: /<a href="([^:\n]*?).md">/g,
   // exclude colon, so external links aren't converted
   replace: '<a href="$1.html">'
-}; // Replace hash links with .html e.g. page.md#Title becomes page.html#Title.
+};
 
+// Replace hash links with .html e.g. page.md#Title becomes page.html#Title.
 const convertMdHashLinksToHtmlLinks = {
   type: 'output',
   regex: /<a href="([^:\n]*?).md#(.*?)">/g,
@@ -17,7 +18,7 @@ const convertMdHashLinksToHtmlLinks = {
 };
 const headingExtension = {
   type: 'output',
-  regex: /<(h[123456]) id="(.*)">(.*)<\/\1>/g,
+  regex: /<(h[123456]) id="([^"]+)">(.*)<\/\1>/g,
   replace: '<$1 id="$2"><a href="#$2">$3</a></$1>'
 };
 const classMap = {
@@ -29,17 +30,13 @@ const bindings = Object.keys(classMap).map(key => ({
   regex: new RegExp(`<${key}(.*)>`, 'g'),
   replace: `<${key} class="${classMap[key]}" $1>`
 }));
-
 const normaliseBasePath = basePath => {
   const pathElements = (basePath || '').split('/').filter(entry => Boolean(entry));
-
   if (pathElements.length === 0) {
     return '';
   }
-
   return '/' + pathElements.join('/');
 };
-
 const createParser = options => {
   const basePath = normaliseBasePath(options.basePath);
   const addBasePathToRootLinks = {
@@ -54,10 +51,8 @@ const createParser = options => {
   parser.setFlavor('github');
   return parser;
 };
-
 const parseToHTML = (markdown, options = {}) => {
   const parser = createParser(options);
   return parser.makeHtml(markdown);
 };
-
 module.exports = parseToHTML;

package/build/page-renderers/Components/Footer.js

@@ -1,9 +1,7 @@
 const React = require('react');
-
 const {
   prettyDate
 } = require('./PrettyDate');
-
 const Styles = {
   footer: {
     bottom: '0',
@@ -20,7 +18,6 @@ const Styles = {
     color: '#337ab7'
   }
 };
-
 const Footer = () => {
   return React.createElement("footer", {
     style: Styles.footer
@@ -29,5 +26,4 @@ const Footer = () => {
     style: Styles.footerLink
   }, "Morty-Docs on github"), React.createElement("br", null), "Page generated on ", prettyDate(new Date()));
 };
-
 module.exports = Footer;

package/build/page-renderers/Components/Header.js

@@ -1,7 +1,5 @@
 const React = require('react');
-
 const getHeaderPaths = require('../../helpers/get-header-paths');
-
 const Styles = {
   navbar: {
     border: 'none',
@@ -28,7 +26,6 @@ const Styles = {
     color: '#ebebeb'
   }
 };
-
 const HeaderLinks = ({
   paths
 }) => paths.map(({
@@ -45,7 +42,6 @@ const HeaderLinks = ({
     href: path
   }, text));
 });
-
 const Header = ({
   relPath,
   basePath
@@ -60,5 +56,4 @@ const Header = ({
     paths: getHeaderPaths(basePath, relPath)
   }))));
 };
-
 module.exports = Header;

package/build/page-renderers/Components/IndexListItem.js

@@ -1,9 +1,6 @@
 const React = require('react');
-
 const IconFileLines = require('./icons/IconFileLines');
-
 const IconFolderOpen = require('./icons/IconFolderOpen');
-
 const Styles = {
   indexListItem: {
     fontSize: '1.5rem',
@@ -28,7 +25,6 @@ const Styles = {
     width: '1em'
   }
 };
-
 const Icon = ({
   iconName
 }) => {
@@ -37,12 +33,10 @@ const Icon = ({
       style: Styles.icon
     });
   }
-
   return React.createElement(IconFileLines, {
     style: Styles.icon
   });
 };
-
 const IndexListItem = ({
   link,
   text,
@@ -61,5 +55,4 @@ const IndexListItem = ({
     style: Styles.linkText
   }, text)));
 };
-
 module.exports = IndexListItem;

package/build/page-renderers/Components/PrettyDate.js

@@ -1,31 +1,23 @@
 const React = require('react');
-
 const nth = function (d) {
   if (d > 3 && d < 21) return 'th';
-
   switch (d % 10) {
     case 1:
       return 'st';
-
     case 2:
       return 'nd';
-
     case 3:
       return 'rd';
-
     default:
       return 'th';
   }
 };
-
 const month = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
-
 const prettyDate = dateObj => {
   const day = dateObj.getDate();
   const year = dateObj.getFullYear();
   return React.createElement(React.Fragment, null, day, React.createElement("sup", null, nth(day)), " ", month[dateObj.getMonth()], " ", year);
 };
-
 module.exports = {
   prettyDate
 };

package/build/page-renderers/Components/Reset.js

@@ -1,5 +1,4 @@
 const React = require('react');
-
 const resetStyles = `/* http://meyerweb.com/eric/tools/css/reset/ 
 v2.0 | 20110126
 License: none (public domain)
@@ -54,11 +53,9 @@ sup {
   padding-right: 0.2rem;
 }
 `;
-
 const Reset = () => React.createElement("style", {
   dangerouslySetInnerHTML: {
     __html: resetStyles
   }
 });
-
 module.exports = Reset;

package/build/page-renderers/Components/Title.js

@@ -1,12 +1,10 @@
 const React = require('react');
-
 const Styles = {
   heading: {
     fontSize: '2rem',
     fontWeight: '500'
   }
 };
-
 const Title = ({
   contentTitle
 }) => {
@@ -22,5 +20,4 @@ const Title = ({
     }, contentTitle));
   } else return null;
 };
-
 module.exports = Title;

package/build/page-renderers/Components/icons/IconFileLines.js

@@ -1,5 +1,4 @@
 const React = require('react');
-
 const IconFileLines = ({
   style
 }) => React.createElement("svg", {
@@ -10,5 +9,4 @@ const IconFileLines = ({
 }, '<!--! Font Awesome Free 6.1.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. -->', React.createElement("path", {
   d: "M256 0v128h128L256 0zM224 128L224 0H48C21.49 0 0 21.49 0 48v416C0 490.5 21.49 512 48 512h288c26.51 0 48-21.49 48-48V160h-127.1C238.3 160 224 145.7 224 128zM272 416h-160C103.2 416 96 408.8 96 400C96 391.2 103.2 384 112 384h160c8.836 0 16 7.162 16 16C288 408.8 280.8 416 272 416zM272 352h-160C103.2 352 96 344.8 96 336C96 327.2 103.2 320 112 320h160c8.836 0 16 7.162 16 16C288 344.8 280.8 352 272 352zM288 272C288 280.8 280.8 288 272 288h-160C103.2 288 96 280.8 96 272C96 263.2 103.2 256 112 256h160C280.8 256 288 263.2 288 272z"
 }));
-
 module.exports = IconFileLines;

package/build/page-renderers/Components/icons/IconFolderOpen.js

@@ -1,5 +1,4 @@
 const React = require('react');
-
 const IconFolderOpen = ({
   style
 }) => React.createElement("svg", {
@@ -10,5 +9,4 @@ const IconFolderOpen = ({
 }, '<!--! Font Awesome Free 6.1.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. -->', React.createElement("path", {
   d: "M147.8 192H480V144C480 117.5 458.5 96 432 96h-160l-64-64h-160C21.49 32 0 53.49 0 80v328.4l90.54-181.1C101.4 205.6 123.4 192 147.8 192zM543.1 224H147.8C135.7 224 124.6 230.8 119.2 241.7L0 480h447.1c12.12 0 23.2-6.852 28.62-17.69l96-192C583.2 249 567.7 224 543.1 224z"
 }));
-
 module.exports = IconFolderOpen;

package/build/page-renderers/IndexPage.js

@@ -1,19 +1,11 @@
 function _extends() { _extends = Object.assign ? Object.assign.bind() : function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
-
 const React = require('react');
-
 const ReactDOMServer = require('react-dom/server');
-
 const Header = require('./Components/Header');
-
 const Title = require('./Components/Title');
-
 const Footer = require('./Components/Footer');
-
 const IndexListItem = require('./Components/IndexListItem');
-
 const Reset = require('./Components/Reset');
-
 const Styles = {
   headingContainer: {
     padding: '40px 15px',
@@ -49,7 +41,6 @@ const Styles = {
     margin: 'auto'
   }
 };
-
 const IndexPage = ({
   listItems,
   options,
@@ -85,11 +76,9 @@ const IndexPage = ({
     key: index
   }, item))))())))), React.createElement(Footer, null)));
 };
-
 const renderIndexPage = (listItems, options, htmlFilePaths) => ReactDOMServer.renderToString(React.createElement(IndexPage, {
   listItems: listItems,
   options: options,
   relPath: htmlFilePaths
 }));
-
 module.exports = renderIndexPage;

package/build/page-renderers/MortyPage.js

@@ -1,13 +1,8 @@
 const React = require('react');
-
 const ReactDOMServer = require('react-dom/server');
-
 const Header = require('./Components/Header');
-
 const Footer = require('./Components/Footer');
-
 const Reset = require('./Components/Reset');
-
 const Styles = {
   wrapper: {
     minHeight: '75vh',
@@ -174,7 +169,6 @@ const contentStyles = `
 }
 
 `;
-
 const MortyPage = ({
   relPath,
   body,
@@ -209,11 +203,9 @@ const MortyPage = ({
     }
   })), React.createElement(Footer, null)));
 };
-
 const renderMortyPage = (relPath, htmlBody, options) => ReactDOMServer.renderToString(React.createElement(MortyPage, {
   relPath: relPath,
   body: htmlBody,
   options: options
 }));
-
 module.exports = renderMortyPage;

package/build/transform-content.js

@@ -1,28 +1,20 @@
 const path = require('path');
-
 const asciidoctor = require('asciidoctor')();
-
 const renderMortyPage = require('./page-renderers/MortyPage');
-
 const parseToHtml = require('./markdown-to-html-parser');
-
 const changeExtension = relPath => relPath.replace(/\.[^.]*$/, '.html'); // \.[^.]*$  selects everything from end of string to first '.' character including the '.'
 
-
 const convertToHtml = ({
   relativePath,
   raw
 }, options) => {
   const textString = raw.toString();
   const ext = path.extname(relativePath);
-
   if (ext === '.asciidoc' || ext === '.adoc' || ext === '.asc') {
     return asciidoctor.convert(textString);
   }
-
   return parseToHtml(textString, options);
 };
-
 const transformContent = (inputObj, options) => {
   const inputRelPath = inputObj.relativePath;
   const html = convertToHtml(inputObj, options);
@@ -31,5 +23,4 @@ const transformContent = (inputObj, options) => {
     raw: renderMortyPage(inputRelPath, html, options)
   };
 };
-
 module.exports = transformContent;

package/build/transform.js

@@ -1,9 +1,6 @@
 const path = require('path');
-
 const transformContent = require('./transform-content');
-
 const generateIndexes = require('./generate-indexes');
-
 const validate = inputObjs => {
   if (!Array.isArray(inputObjs)) throw new Error('First arg to transform() must be an array');
   inputObjs.map(inputObj => {
@@ -11,12 +8,10 @@ const validate = inputObjs => {
     if (typeof inputObj.relativePath === 'undefined') throw new Error('All objects in input array must have a .relativePath property');
   });
 };
-
 const transform = (inputObjs, options) => {
   validate(inputObjs);
   const contentObjs = inputObjs.map(inputObj => {
     const ext = path.extname(inputObj.relativePath);
-
     if (ext === '.md' || ext === '.asciidoc' || ext === '.adoc' || ext === '.asc') {
       return transformContent(inputObj, options);
     } else {
@@ -26,5 +21,4 @@ const transform = (inputObjs, options) => {
   const indexObjs = generateIndexes(contentObjs, options);
   return [...contentObjs, ...indexObjs];
 };
-
 module.exports = transform;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bbc/morty-docs",
-  "version": "1.12.2",
+  "version": "3.0.1",
   "description": "To generate a static website from markdown documentation, to allow users to consume content in an easily accessible format",
   "main": "build/index.js",
   "publishConfig": {
@@ -31,7 +31,8 @@
     "markdown"
   ],
   "engines": {
-    "node": ">=12.x"
+    "node": ">=18.x",
+    "npm": ">=8.x"
   },
   "author": "BBC",
   "license": "Apache-2.0",
@@ -55,7 +56,7 @@
     "@babel/preset-react": "^7.0.0",
     "babel-eslint": "^10.0.3",
     "http-server": "^14.1.1",
-    "jest": "^28.1.2",
+    "jest": "^29.7.0",
     "jest-serializer-html": "^7.0.0",
     "standard": "^12.0.1"
   },