Summarymd

Last version

• Fix: excludes not work。 排除设置不生效。
• Use inquirer for commands。

v2.0.1

• Support for HTML files.

V2.0.0+ is a new version, the previous interface is no longer supported!!! 中文 Readme

Summymd can:

1. Summymd makes the process of creating files controllable and customizable.

   • You can decide which header to use —— you can use "*", "=", custom YAML headers, etc.

     YAML headers cannot be parsed accurately (this module relies on markdown-it to parse markdown). This affects the accuracy of creating temporary directories. Unless you add a markdown tag after the YAML header that resolves to <h1>... </h1>.

   • Instead of just creating an empty document with a title like Gitbook, you can add some specific text content in batches.

2. Summymd makes the way to generate directory lists controllable.

   • Variable Link Text - You can use the file name as the link text, regardless of the title of the article;

   • Version v2.0.0+ supports indentation based on matching specific characters (whether characters in paths or titles are matched by regular expressions), ignoring the nesting relationship of folders. This facilitates the grouping of documents with similar or related content.

   • Supports folder indentation once per level (default indentation).

   Indentation is used to make it easier to sort out the order of documents ——for those documents that are not included in the summary list file, you need to manually adjust the order of documents before they are included, and then manually append them to the real summary file (such as summary.md). (The summary list generated by this package is only a temporary markdown file with the default file name: "_summary.md".

3. Print Problems with lists in SUMMARY.md:

   • File paths that do not exist (original files are deleted, moved, renamed, empty paths, or inaccurate paths, of course, may not have been created), but SUMMARY.md did not modify or create the file.

   • No text links. For example: [](doc/example.md)

   This design is only embodied on the command line: summarymd status or summarymd-s, if used in the project module, the corresponding return value can be obtained by ._summaryStatus_hasProblems().problem_with_URL and ._summaryStatus_hasProblems().problem_with_Text.

Installation of cable vehicles

1. Install into the project:

   npm i summarymd

2. Global Installation:

   npm i -g summarymd

   Run summarymd-h after global installation to get command line support functions and usage.

Usage

1. Introduce to the project.

const summarymd = require ('summarymd')

const SM = new summarymd ()// must use with new keyword.

// change configs

// When creating a file, use the name of the file as the first-level title of the document.

SM.configs.confs_with_create.isUseFileBasenameAsTitle = true;


// Use "+" as a list tag.

SM.configs.confs_with_summary.listSing='+';

//... You can change more configuration items to create files or create temporary directories



// Create a markdown file from the summary file.

SM.create ((t)=> {return `# ${t} \n [TOC] `})

/** After the file is created, the contents are similar:

# Example
  
[TOC]

 */

SM.update ()// Generate temporary directories.

2. Global installation, used as a command.

There are many configuration items, so it's troublesome to use command parameters alone. We use configuration files to deal with how to create files and how to update temporary directories.

• First, create the configuration file to the project work path (`summaryConfig. js'):

  Summymd init

  If you want to reset the configuration file, execute summarymd reinit.

• Next, change the configuration file and save it according to your needs, such as setting indentation, list tags, document template functions, etc.

• After completing the first two steps, you can now work with commands:

  Summarymd create

  Create a file.

  Summymd update

  Update the temporary directory with update.

  Summary Watch

  Watch automatically monitors file changes and automatically executes summarymd create and summarymd update.

configuration file description

1. Project references are used by the new keyword, and then reassigned to the specified configuration item.

Source code:

this.configs={

    // Files to be processed (Path completion, even if "./SUMMARY.md" and "SUMMARY.md" are equivalent, but must be written as "./SUMMARY.md")

    include: ['./**/*.md','./**/*.markdown'],
    // Formal directory file path (path to be completed, even if "./SUMMARY.md" and "SUMMARY.md" are equivalent, but must be written as "./SUMMARY.md")
    summary: "./SUMMARY.md",

    // Configuration of Creating Files
    confs_with_create:{ 
        /**
         * Whether to skip lists with empty URLs or empty link text when creating files.
         */
        isSkipEmptyTitleOrEmptyPath:true,
        // Remote path matching expressions (remote files cannot be created, you can try to download them if you can, but they can only be excluded here)
        remoteURLregexp: /(\w\:\/|(\.\.\/)|(\:\\\\)|(\w+\:\d+)|\~\/|(\d.+\.\d).[\/|\:\?]?)|((\w\.[\w|\d]).*\/.+([\/]|\:\d|\.html|\.php|\.jsp|\.asp|\.py))/g
    },

    // Update Temporary Directory Configuration
    confs_with_summary:{

        // Temporary directory file path (path to be completed, even if "./SUMMARY.md" and "SUMMARY.md" are equivalent, but must be written as "./SUMMARY.md")
        tempSummary: ". /_summary. md",

        // Does the file name serve as the text of the link to the directory list?
        isUseBFasLinkText: false,

        // List Markup Symbol
        listSing: "*",
        // Whether to perform URL encoding for links in the directory list.
        isEncodeURI: false,

        // Configuration of directory list indentation
        indent: {
            // Whether to use indentation or not.
            isIndent: true,

            // indentation length
            indentLength: 4,

            // indent by "IndentByDirs" or "IndentByTitle"

            /**
             *
             * It must be in this format (both IndentByDirs and IndentByTitle):
             * @example
             *
             * [{basis:/\/js\//,times:1},...]
             *
             * key:  basis - The indentation rule, preferably a regular expression, is used in the code to test whether the indentation rule matches with the "basis.test()".
             * 
             * key: Times - The number of indentations must be numeric, and the final indentation = .indentLength * times .
             *
             * Note:
             *
             * IndentByDirs and IndentByTitle cannot be defined simultaneously. Define one, and the other should be null.
             */
            IndentByDirs: null,
            /**@see IndentByDirs*/
            IndentByTitle: null,
        }
    }
}

// Documents to be excluded.

this.excludes = ['!./node_modules/**/*. *','!'+this.configs.summary,'!'+this.configs.confs_with_summary.tempSummary]

2. Configuration instructions as command line usage

The configuration file is generated by: summarymd init. The generated file is: ./summaryConfig.js. It's contents are as follows:

// you can add more property if you need(Different from defaults). but don't del the default propertys(you can change the value).
// Why not JSON? For the summarymd module, you can redefine anything and use JavaScript files to customize configuration files with greater freedom. 
// If you need more customization, consider using the summarymd module instead of the command line.

const confs ={
    // 
    // it's just a default string ,you can do more. the "%title%" will be replaced by true title. 
    template: "# %title%",
    includes: ['./**/*.md', './**/*.markdown'],
    excludes:['!./node_modules/**/*.*'],
    // Official directory file path.
    summary: "./SUMMARY.md",
    confs_with_create: {
        /**
         * Whether to skip lists with empty URLs or empty link text when creating files.
         */
        isSkipEmptyTitleOrEmptyPath:true,
        // Remote Path Matching Rules--This package does not handle any remote paths unless the matched rules fail to match.
        remoteURLregexp: /(\w\:\/|(\.\.\/)|(\:\\\\)|(\w+\:\d+)|\~\/|(\d.+\.\d).[\/|\:\?]?)|((\w\.[\w|\d]).*\/.+([\/]|\:\d|\.html|\.php|\.jsp|\.asp|\.py))/g,
        },
    confs_with_summary: {
        // Temporary directory file path
        tempSummary: "./_summary.md",
        // Whether to use the base file name as link text.
        isUseBFasLinkText: false,
        // Markdown List Markup Symbol
        listSing: "*",
        // 
        isEncodeURI: false,
        indent: {
            // Whether to perform URL encoding for links in the directory list.
            isIndent: true,

            // Number of spaces indented once. The actual indentation of this module = indentLength * times. According to the current configuration, indentation twice is to indent eight spaces.
            indentLength: 4, 

            /*
            The following two configurations control custom indentation rules in the basic format:
            
                [{basis:/npm/g, times:1}]

            basis - indentation rule, type: regular expression
            times - Indentation times.
            
            The above example shows that the matching to "npm" is indented once.

            NOTE:You can't set them up at the same time. You can only choose one way to generate temporary directory files. Set both to null if you don't need to customize indentation rules.
            */
            IndentByDirs: null,
            IndentByTitle: null,
        }
    }
}
module.exports = {
    confs
}

It's similar to the module reference method, just to redefine the default values as simply as possible and make some changes... Anyway, it feels very complicated! Configuration files in JSON format are not easy to use variant additions —— especially when creating new documents in batches, such as date and time. In comparison, it is better to deploy a temporary NPM project directly than to use the command line...

Methods

Note: The values of class attributes configs. include'and configs. excludes' and the contents of directory files (e.g. `summary. md') determine the return value of the function.

• .create(template [,Function])- Create files in the directory list, and existing files will be skipped. * This requires a "summary.md" file or other file with a similar list. *

  Function must be provided and at least one parameter must be defined for internal headings. The defined function must return the string content. For example:

  example. create ((title) => {return `${title} n=== n Add more contents. `});

  The return value of the function will be the content of the new file. If the function returns undefined, the content of the new file will be similar to "# example"

• .update()- Update directory list. The updated content is stored in the temporary directory file (default path: . /_summary. md').

• .localDocs().docPaths- The path to return the local existing document. Array, the result is similar to: ["example. md,...].

• .localDocs().docs- Returns the title and path of the local existing document. The result is similar to: [{title:'example', path:'example.md'},...].

• .summyList()- Returns the link information for the directory list. The results are similar to: [{title:'example', path:'example.md'}].

• .docs_not_list_in_summary()- Returns document information that already exists locally but has not yet been included in the catalog file. The results are similar to: [{title:'example', path:'example.md'}].

• ._summaryStatus_hasProblems().problem_with_URL- Returns a list of files in a directory file that do not have paths or URLs pointing to that do not exist. The results are similar to: [{title:'example', path:'example.md'}]Or [].

• . _summaryStatus_hasProblems().problem_with_Text- Returns a list of links with empty links in the directory folder. The results are similar to: [{title:'example', path:'example.md'}]or [] .