summarybuilder

中文 README >>.

Mainly used for gitbook and gadgets like it with the SUMMARY.md project plugin (currently only supports .md types), for two purposes:

1. Based on the existing list of files already listed in SUMMARY.md, create them in batches (` existing files will be ignored);

2. Create a list of SUMMARY.md based on the existing .md file.Will not directly rewrite the SUMMARY.md file, will generate a: _summary.md file to the project root directory, need to manually adjust the order and then copy and paste into your project SUMMARY.md file.

3. In fact, it can be used for any directory where .md files exist. You can also import the summarybuilder module to the project's gulp task.

   NOTE:

   • Files and folders that have been excluded by default (* only when run as a command, nothing is excluded when introduced as a node module*)：

   [
       '!SUMMARY.md', 
       '!node_modules/**', 
       '!_summary.md'
   ]

   • Before deleting using git, delete the file generated by the plugin or write it in .gitignore to exclude it.**。

   # tmp files
   _summary.md
   .li.json

Changes in new version

v 1.4.6

• Provide support for kc-cli

v 1.4.5

• Fixed a situation where the '*[example(new)](docs/example.md)' entry in the SUMMARY.md file would become 'new]docs/example.md' when it was created.

  Note: Although this BUG is basically fixed but not completely avoidable, it will trigger when this happens: '* [hello[the](world)](htw.md)', even This kind of writing can't be rendered normally (the rendering result is not: 'hello[the](world)'.well, It look as a Markdown syntax error), but if it exists, it will be forced to render (not because of " The error "terminates, it still works, even if it is not what we want). Therefore, you should not use this type of conflicting stash in the SUMMARY.md file or in the headers of other ".md" files.

v 1.4.4

• Add 'use strict'.

V 1.4.3 ：

• Entries that already exist in SUMMARY.md will no longer appear in the _summary.md file. Eliminating the need to repeat manual adjustments.
• Fixed an issue where headers had extra prefix spaces.

Install

• Add to your project。

  npm install --save summarybuilder

• global

  npm install -g summarybuilder

Commands

command | description -------------|----------------- summary -c | Create files that are listed in SUMMARY.md, and existing files will skip. summary -b | Generate the file'_summary.md' . summary -b -t | Use indentation in the creation of _summary.md. Ps: this will make the level clearer (default by folder structure indent). summary -b -t [ignores] | [ignore]：Exclude files that you do not want to add to _summary.md and use indentation.example：summary -b -t '!docs/foo/*.md'# Exclude multiple:summary -b -t '!/exc/**' !test/**/.md' '!one/two/*.mdNote: "!" maybe cause ambiguity When using bash. should use ' or " around it. summary -d | Delete files(./.li.json 、 ./_summary.md)

Example( run as command with terminal )

The _summary.md file is generated and indented (does not exclude any files).

summary -b -t

Generate _summary.md and exclude unnecessary files. Explain that in order to take into account the gulp.src([...]) parameter format,to exclude multiple folders (files) separated by spaces when using command line operations,the "!" symbol may appear to cause bash ambiguity. The error interrupted operation needs to be wrapped with the ['] or the ["] :

summary -b '!/exc/**'

or

summary -b -t "!/exc/**"

Exclude multiple files/folders (different files, folders separated by spaces):

summary -b -t '!/exc/**' '!test/**' '!one/two/xx.md'

Require summarybuilder as node module

Example（as a module）

gulpfile.js:

const sm = require('summarybuilder');
const gulp = require('gulp');
const gulpfl = require('gulp-filelist');

//The gulp task to create files which listed in SUMMARY.md(or another file has same format like SUMMARY.md)

gulp.task('create', function () {
    sm.SBer_createMD("./SUMMARY.md", "By summarybuider");
});

// Create a JSON file to list  all of Markdown files that you wanted to add to SUMMARY.md.

gulp.task('list', function () {
    gulp.src('test/**/*.md')
        .pipe(gulpfl('list.json'))
        .pipe(gulp.dest('test'));
});

// Add a watch task to run it when some file changed.

gulp.task('watcher', function () {

    gulp.watch('test/**/*.md', ['list']);

    gulp.watch('test/list.json', function () {
        sm.SBer_summary('./test/list.json', false, 'sm.txt'); // The contens of sm.txt is same as SUMMARY.md
    });
});

// ---------- v1.4.2 -------------------
// maybe, need a JSON file is bad idea. we need easier method.
sm.SBer_summaryMDs(['-t','./**/*.md','!Docs/**/*.md','!README.md']);

// '-t' means indent, If you don't want it to be indented. just like this:
sm.SBer_summaryMDs(['./**/*.md','!Docs/**/*.md','!README.md']);

// maybe you need gulp task.
gulp.task('summary',()=>{
    sm.SBer_summaryMDs(['-t','./**/*.md','!Docs/**/*.md','!README.md']);
    console.log('Task: summary done');
});

// The files '_summary.md' and '.li.json' wuld be created after you run the task.

API

1. SBer_summary() :Generates a file similar to SUMMARY.md.

SBer_summary( jsonFileName, isIndent, outFileName )

• jsonFileName：type: string OR Array——The path of the JSON file.It is better to be created by the plugin: gulp-filelist. Or like this:

  SBer_summary(["a.md","b/a.md"],true,"mySummary.md")
  
  // Note: Wildcard paths are not supported and must be a specific array of markdown file paths.

  JSON格式的列表文件路径 example：allMDlist.json:（NOTE: 注意保留完整路径，以便读取。）

  [
  "./a/a.md",
  "./b/b.md"
  ]

• isIndent: type: Boolean ——Indent? If true will be indented.Must true or false.

• outFileName: type: string—— example: "a.md",Any you wanted if you sure it can be read.

Example:

const sm = require('summarybuilder');

const mdFiles = [
    'a.md',
    'b.md',
    'test/x/y/z.md'
]

sm.SBer_summary(mdFiles,true,'_summary.md');

// or like this

sm.SBer_summary(['a.md','b.md','test/x/y/z.md'],true,'_sm.md');

2. SBer_createMD(): Create a corresponding markdown file。

SBer_createMD( summaryFilePath )，Create a corresponding markdown file based on a list similar to SUMMARY.md.

• summaryFilePath:type: string——The path to the file with the same format as SUMMARY.md (of course, you can also use the path to SUMMARY.md directly).

• arguments[1]: type: string——Add content other than the title, which can be the body part of Markdown (* The first # tag already exists. If not, it is better not to repeat the *).

  xxx.md

  * [TEST](./a/TA)

  xx.js:

  // just title.
  
  SBer_createMD('./SUMMARY.md');
  
  // Add some content.
  
  SBer_createMD('./SUMMARY.md','This is a test content!');
  

  result ( If no error :< )：

  # TEST
  
  This is a test content!

3. SBer_summaryMDs(array)

Note: Ensure that the given value does not trigger the "Missing positive glob" and you need to make sure that there are files that can be matched into the pipe() stream. Otherwise, it will report an error and exit the process.

example：

//...
SBer_summaryMDs(['-t','./**/*.md','!Docs/**/*.md','!README.md']);

// '-t' means indent, If you don't want it to be indented. just like this:

SBer_summaryMDs(['./**/*.md','!Docs/**/*.md','!README.md']);

// You can use it like this:
SBer_summaryMDs(['-t']);



// But like this will report error:
SBer_summaryMDs(['!README.md']);
// or 
SBer_summaryMDs(['-t','!README.md']);

// Them will report an error both,because gulp.src(['!README.md']) can't get any thing from stream.

The difference between SBer_summaryMDs(array) and SBer_summary( jsonFileName, isIndent, outFileName ):

• SBer_summaryMDs(array) supports wildcard paths,But SBer_summary() does not support.
• SBer_summaryMDs(array) : You can avoid the trouble of using gulp-filelist to generate JSON files.

Donate to author

QR code for WeChat

Licence

MIT