https://github.com/varlinor/magic-md2html

a plugin for generate html from your own template
https://github.com/varlinor/magic-md2html

gulp-plugin markdown marked md md2html transformer

Last synced: 22 days ago
JSON representation

a plugin for generate html from your own template

• Host: GitHub
• URL: https://github.com/varlinor/magic-md2html
• Owner: varlinor
• License: mit
• Created: 2018-07-13T13:38:07.000Z (over 6 years ago)
• Default Branch: master
• Last Pushed: 2020-06-09T10:02:45.000Z (over 4 years ago)
• Last Synced: 2024-11-28T08:07:28.711Z (about 1 month ago)
• Topics: gulp-plugin, markdown, marked, md, md2html, transformer
• Language: CSS
• Size: 41 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.MD
  • License: LICENSE
  • Roadmap: RoadMap.md

Awesome Lists containing this project

README

        
# magic-md2html

>something you want to know quickly:

>>[5 minutes user guide](https://github.com/varlinor/magic-md2html/wiki/5-minutes-User-guide)  

>>[ChangeLog](https://github.com/varlinor/magic-md2html/wiki/Change-Log)  

>>magic-md2html default stylesheets [refer to](https://github.com/varlinor/magic-style)  

Based on [marked](https://www.npmjs.com/package/marked);

Use marked.Renderer to control html class

This tool is used to batch generate html whit your custom html template!

firstly, you need a html template, just like this:

```

    

{{meta}}

{{cssHref}}

    {{title}}

{{content}}

{{footer}}

{{extraScript}}


```

secondly, write extra content file, just like metaInfo, footer, extraScript, style files, etc. you can find

examples in directory `test/attachfiles`.

finally, prepare some markdown files, set configuration and run gulp task!

Then you can obtain your html file in dist directory!

## Custom extends for markdown

for test, perhaps simple to study other tools in npm registry, I add two kinds of extend in md file.

1. ToC tag

2. label tag

you can use them as simple as possible, just like this:

* add `` tag in your md file, then this tool will auto create ToC at where you marked the tag.

* add `` tag in your md file, then this tool will auto create labels with `
` at where you marked the tag.


of course, you need your own style file to control how ToC and labels display.

>for example, I write some css for them, you can add see them at `test.html` ( refer to `test/base.css`),

>it contains full css for content from md file.

>>PS: the stylesheets in test.html >> [magic-style](https://github.com/varlinor/magic-style)

## html template fields

`{{meta}}` means where to replaced meta info in html, used to SEO information.

`{{author}}` inner setting, you can see it in `index.js`, used to replaced with md file author.

it will be allowed to get real author in md file if you announced in file, the feature will release on next version.

`{{description}}` inner setting, you can see it in `index.js`, same with field `author`, used to replaced with description in md file.

`{{cssHref}}` used to replaced attached file which contains css link info, just like ``

`{{title}}` used to replaced with html title when transform md file.

`{{content}}` used to replaced html tags which transformed by `marked` that the content in md file.

`{{extraScript}}` used to add some common script to html file, this field will be replaced with content in pointed extra file, refer to configuration: `extraScriptPath`

`{{footer}}` used to add some common footer, just like statistics script, common info, links to business partner, etc.

Also, this field will be replaced with content in pointed extra file, refer to configuration: `footerPath`

## Configuration

    debugMode:false,

    buildTemplate: false, 

    enableToC:false,

    templatePath:'',

    cssFilePath:'',

    extraScriptPath:'',

    footerPath:'',

    metaInfo:{

        author:'',

        copyright:''

    }

    markedOptions:{},

### debugMode

bool, default is false, to control whether output debug info in console.

### buildTemplate

bool, default is false, to control whether pre build html template or not!

if set `false`, your html template must has no these fields:

* {{cssHref}}

* {{footer}}

* {{extraScript}}

whether buildTemplate exist or not, the field `{{content}}` is required for replaced with md content.

### enableToC

bool, default is false, to control whether generate ToC tags from `
`,`
`,`
` or not.


### templatePath

string, this field is required in options, if you hasn't set `buildTemplate:true`,

this field must point the path of html template with limited template fields;

>for example, in dir `test`, if I set `buildTemplate:true`,

>the field `templatePath` must be filled with `./test/index.template.html`.

>If I set `buildTemplate:false`, the field `templatePath` should be pointed at path of `./test/template.html`.

### cssFilePath

string, if you set `buildTemplate:true`,

you can point the file which contains the stylesheet fragment what will be replaced with `{{cssHref}}` in html template.

Just like `` or ``.

### extraScriptPath

string, if you set `buildTemplate:true`,

you can point the file which contains the extra script fragment file what will be replaced with `{{extraScript}}` in html template.

### footerPath

string, if you set `buildTemplate:true`,

you can point the file which contains the extra footer html fragment what will be replaced with `{{footer}}` in html template.

### metaInfo

object, contains two field: `author` and `copyright`, if all md files are from same author,

you can set author here globally.

* `author` will be replaced in meta tag like ``

* `copyright` will be formatted in meta tag like ``

>PS: if pointed author in md file, this global setting will be covered, perhaps next version will add this feature.

### markedOptions

object, this object represent `marked` [options](https://marked.js.org/#/USING_ADVANCED.md#options),

so we can set `markedOptions.renderer` to customize your own style for all these elements below:

```

Block level renderer methods

- code(*string* code, *string* language)

- blockquote(*string* quote)

- html(*string* html)

- heading(*string* text, *number*  level)

- hr()

- list(*string* body, *boolean* ordered)

- listitem(*string*  text)

- paragraph(*string* text)

- table(*string* header, *string* body)

- tablerow(*string* content)

- tablecell(*string* content, *object* flags)

`flags` has the following properties:

{

    header: true || false,

    align: 'center' || 'left' || 'right'

}

Inline level renderer methods

- strong(*string* text)

- em(*string* text)

- codespan(*string* code)

- br()

- del(*string* text)

- link(*string* href, *string* title, *string* text)

- image(*string* href, *string* title, *string* text)

- text(*string* text)

```

## Some Ideas

Originally, I think perhaps I should set css class as variables in this configuration, just like format below:

```

options={

    ...

    tagClassDef:{

        blockquoteClass:'',

        hrClasss:'',

        olClass:'',

        ulClass:'',

        pClass:'',

        tableClass:'',

        strongClass:'',

        aClass:'',

        emClass:'',

        spanClass:'',

        imgClass:'',

        delClass:'',

    }

}

```

but, I think that's so stupid to do this.

Everyone can set their own styles, why should I limited the html format which transformed by `marked`.

## To User

This tool may not be so perfect to generate such a beautiful html pages, it comes from an idea by suddenly,

it is simple, but just matches my requirement. if you have some ideas for it, please let me know, thank you!