13 |
20 | This file contains the bulk of the logic for generating
21 | litterate pages. This file exports a function that the
22 | command-line utility calls with configurations.
23 |
4
5const fs = require('fs');6const path = require('path');Marked is our markdown parser
27 |
8const marked = require('marked');This isn't optimal, but for now, we read the three template files into memory at the beginning,
30 | synchronously, so we can reuse them later.
31 |
12const INDEX_PAGE = fs.readFileSync(path.resolve(__dirname, '../templates/index.html'), 'utf8');
13const STYLES_CSS = fs.readFileSync(path.resolve(__dirname, '../templates/main.css'), 'utf8');
14const SOURCE_PAGE = fs.readFileSync(path.resolve(__dirname, '../templates/source.html'), 'utf8');
Helper function to wrap a given line of text into multiple lines,
36 | with limit characters per line.
37 |
18const wrapLine = (line, limit) => {19 const len = line.length;
21 for (let countedChars = 0; countedChars < len; countedChars += limit) {22 result += line.substr(countedChars, limit) + '\n';
Helper function to scape characters that won't display in HTML correctly, like the very common
47 | > and < and & characters in code.
48 |
29const encodeHTML = code => {30 return code.replace(/[\u00A0-\u9999<>&]/gim, i => {31 return '&#' + i.codePointAt(0) + ';';
Litterate uses a very, very minimal templating system that just wraps keywords
55 | in {{curlyBraces}}. We don't need anything complicated, and this allows us to be
56 | lightweight and customizable when needed. This function populates a template with
57 | given key-value pairs.
58 |
39const resolveTemplate = (templateContent, templateValues) => {40 for (const [key, value] of Object.entries(templateValues)) {41 templateContent = templateContent.replace(
42 new RegExp(`{{${key}}}`, 'g'),46 return templateContent;
Function that maps a given source file to the path where its annotated version
69 | will be saved.
70 |
51const getOutputPathForSourcePath = (sourcePath, config) => {53 config.outputDirectory,
Function to populate the index.html page of the generated site with all the source
78 | links, name/description, etc.
79 |
60const populateIndexPage = (sourceFiles, config) => {61 const files = sourceFiles.map(sourcePath => {62 const outputPath = getOutputPathForSourcePath(sourcePath, config);
63 return `<p class="sourceLink"><a href="${config.baseURL}${path.relative(config.outputDirectory, outputPath)}">${sourcePath}</a></p>`;65 return resolveTemplate(INDEX_PAGE, {67 description: marked.parse(config.description),
68 sourcesList: files.join('\n'),69 baseURL: config.baseURL,
Given an array of source code lines, return an array of lines matched with
93 | any corresponding annotations and the line number from the source file.
94 |
75const linesToLinePairs = (lines, config) => {Shorthand function to markdown-process and optionally wrap
99 | source code lines.
100 |
81 const processCodeLine = codeLine => {82 if (config.wrap !== 0) {83 return wrapLine(encodeHTML(codeLine), config.wrap);
85 return encodeHTML(codeLine);
linesToLinePairs works by having two arrays -- one of the annotation-lineNumber-source line
109 | tuples in order, and another of the annotation lines counted so far for the next source line.
110 | This takes the annotation, line number, and source line from the second array and pushes it
111 | onto the first array, so we can move onto the next lines.
112 |
93 let inAnnotationComment = false;
94 const pushPair = (codeLine, lineNumber) => {96 const lastLine = linePairs[linePairs.length - 1];
97 if (lastLine && lastLine[0]) {98 linePairs.push(['', '', '']);
100 linePairs.push([marked.parse(docLine), processCodeLine(codeLine), lineNumber]);
102 linePairs.push(['', processCodeLine(codeLine), lineNumber]);
Push the current annotation line onto the array of previous annotation lines,
127 | until we get to the next source code line.
128 |
109 const pushComment = line => {110 if (line.trim().startsWith(config.annotationStartMark)) {111 docLine = line.replace(config.annotationStartMark, '').trim();
113 docLine += '\n' + line.replace(config.annotationContinueMark, '').trim();
The main loop for this function.
137 |
118 lines.forEach((line, idx) => {119 if (line.trim().startsWith(config.annotationStartMark)) {120 inAnnotationComment = true;
122 } else if (line.trim().startsWith(config.annotationContinueMark)) {123 if (inAnnotationComment) {126 pushPair(line, idx + 1);
129 if (inAnnotationComment) {130 inAnnotationComment = false;
132 pushPair(line, idx + 1);
This function is called for each source file, to process and save
159 | the Litterate version of the source file in the correct place.
160 |
141const createAndSavePage = (sourcePath, config) => {142 const logErr = err => {144 console.error(`Error writing ${sourcePath} annotated page: ${err}`);148 return new Promise((res, _rej) => {149 fs.readFile(sourcePath, 'utf8', (err, content) => {154 const sourceLines = linesToLinePairs(content.split('\n'), config).map(([doc, source, lineNumber]) => {155 return `<div class="line"><div class="doc">${doc}</div><pre class="source javascript"><strong class="lineNumber">${lineNumber}</strong>${source}</pre></div>`;158 const annotatedPage = resolveTemplate(SOURCE_PAGE, {161 baseURL: config.baseURL,
163 const outputFilePath = getOutputPathForSourcePath(sourcePath, config);
164 fs.mkdir(path.parse(outputFilePath).dir, {recursive: true}, err => {169 fs.writeFile(outputFilePath, annotatedPage, 'utf8', err => {This whole file exports this single function, which is called with a list of files
200 | to process, and the configuration options.
201 |
182const generateLitteratePages = (sourceFiles, config) => {Write out index and main.css files
207 |
188 fs.mkdir(outputDirectory, {recursive: true}, err => {190 console.error(`Unable to create ${outputDirectory} for documentation`);194 path.resolve(outputDirectory, 'index.html'),
195 populateIndexPage(sourceFiles, config),
198 console.error(`Error encountered while writing index.html to disk: ${err}`);203 fs.writeFile(path.resolve(outputDirectory, 'main.css'), STYLES_CSS, 'utf8', err => {205 console.error(`Error encountered while writing main.css to disk: ${err}`);Process source files that need to be annotated
230 |
211 for (const sourceFile of sourceFiles) {212 createAndSavePage(sourceFile, config);
213 console.log(`Annotated ${sourceFile}`);218 generateLitteratePages,
This file is the entry point for the command-line utility,
23 | and is focused on handling and processing CLI arguments and
24 | figuring out the right options to pass to the docs generator.
25 |
6
We use minimist to parse command line arguments (process.argv)
28 |
8const path = require('path');9const minimist = require('minimist');10const glob = require('glob');11const DEFAULTS = require('./defaults.js');12const {generateLitteratePages} = require('./generate.js');Read + parse command line arguments into a dictionary (object)
35 |
15const ARGS = minimist(process.argv.slice(2));
17if (ARGS.help || ARGS.h) {19 litterate - generate beautiful literate programming-style code annotations
20 Read the full documentation at https://github.com/thesephist/litterate
24 litterate --config your-litterate-config.js
25 litterate [options] [files]
26 (if no files are specified, litterate runs on src/**/*.js)
29 (these can be customized in a configuration file as well)
31 --config Specify a JS or JSON file for configuration
33 -n, --name Name of your project, shown in the generated site.
36 Description text for your project, shown in the generated site.
38 -w, --wrap If 0, long lines of source code will never be wrapped.
39 If any other number, litterate will wrap long lines to the given
40 number of characters per line.
43 By default, the generated website assumes the root URL of the site
44 is '/', but for GitHub Pages and other sites, you may want to set
45 a different base URL for the site. This allows you to set a different
49 Verbose output while litterate runs, useful for debugging.
52 Specify a different destination directory for the generated docs site.
53 By default, litterate writes to ./docs/.
55 console.log(helpMessage);
It's OK to process.exit() here because it'll always be
77 | the top-level execution layer of the app, as the entry point to the CLI.
78 |
58 /* eslint-disable-next-line no-process-exit */
62const userConfigPath = ARGS.config;
63const USER_CONFIG = userConfigPath ? require(path.resolve(process.cwd(), userConfigPath)) : {};This is an easy way to merge two configuration options, with USER_CONFIG overriding anything
85 | specified in defaults.
86 |
66const CONFIG = Object.assign(
Reconcile ARGS, the command-line arguments, and CONFIG together; ARGS overrides
93 | any CONFIG file option.
94 |
74for (const [optionName, optionValue] of Object.entries(ARGS)) {77 // do nothing -- ignore
80 if (optionValue.length > 0) {81 CONFIG.files = optionValue;
86 CONFIG.name = optionValue;
90 CONFIG.description = optionValue;
94 CONFIG.wrap = parseInt(optionValue, 10);
98 CONFIG.baseURL = optionValue;
102 CONFIG.verbose = optionValue;
106 CONFIG.outputDirectory = optionValue;
109 throw new Error(`${optionName} is not a valid option, but was set to ${optionValue}`);File names are given as glob patterns, which we should expand out.
134 |
114let sourceFiles = [];
115for (const globPattern of CONFIG.files) {Calling the synchronous API here is find, since this is a CLI with one event
138 | in the loop, but it may be faster to switch to the async version later.
139 |
119 const files = glob.sync(globPattern, {This option excludes any directories from the returned match, which we want.
142 |
121 nodir: true,
Ignore node modules in matches
145 |
123 ignore: [
127 sourceFiles = sourceFiles.concat(files);
129 console.log(`Error encountered while looking for matching source files: ${err}`);Ensure that the base URL ends with a /
156 |
134CONFIG.baseURL = path.join(CONFIG.baseURL, '/');
137 console.log('Using configuration: ', CONFIG);140generateLitteratePages(sourceFiles, CONFIG);