markdown-styles - npm Package Compare versions

Comparing version 2.2.0 to 2.3.0

lib/pipeline.js

@@ -9,2 +9,22 @@ var fs = require('fs'),
 module.exports = function(argv) {
+  // custom rendered for headings
+  var renderer = new md.marked.Renderer();
+  // if we want to generate header links, override the default header renderer
+  if (argv['header-links']) {
+    renderer.heading = function(text, level, raw) {
+      var id = this.options.headerPrefix + raw.trim().toLowerCase().replace(/[^\w]+/g, '-');
+      return '<h' +
+        level +
+        ' id="' +
+        id +
+        '">' +
+        '<a class="header-link" href="#' +
+        id +
+        '"></a>' +
+        text +
+        '</h' +
+        level +
+        '>\n';
+    };
+  }
   return pi.pipeline([
@@ -20,3 +40,5 @@ md.parseHeader(),
       }),
-      md.convertMd(),
+      md.convertMd({
+        renderer: renderer
+      }),
 
@@ -23,0 +45,0 @@ // map paths

package.json

 {
   "name": "markdown-styles",
   "description": "Markdown to HTML generator and multiple CSS themes for Markdown",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "author": {
@@ -32,4 +32,4 @@ "name": "Mikito Takada",
     "handlebars": "~2.0.0",
-    "markdown-stream-utils": "~1.0.2",
-    "mkdirp": "0.3.5",
+    "markdown-stream-utils": "~1.1.0",
+    "mkdirp": "~0.5.1",
     "pipe-iterators": "~1.1.0",
@@ -36,0 +36,0 @@ "resolve": "~0.6.1",

readme.md

@@ -9,24 +9,27 @@ # markdown-styles
 
-- `v2.0` is a major rewrite, with significant usability improvements; the core has been rewritten to use object mode streams via [pipe-iterators](https://github.com/mixu/pipe-iterators).
+- `v2.3` adds one new feature: header hover anchor links. When you hover over a header, a hover anchor link appears to the side of the header. Clicking on that link or copying its URL produces a link to that specific location on the page. All built-in layouts support this feature by default.
+- `v2.2` added Windows support (!)
 - Includes 15+ ready-made CSS stylesheets for Markdown, see the bottom of the readme for screenshots.
 - Reuse the stylesheets or use the `generate-md` tool to convert a folder of Markdown files to HTML using one of the built-in layouts or a custom layout.
 - Completely static output is easy to host anywhere.
-- Metadata support: Each file can include additional metadata in a header section (new in 2.0!), such as the page title and author name which can then be used in the layout.
-- Layout features:
-  - Built in support for code syntax highlighting via highlight.js (new in 2.0!)
-  - All layouts now include a Github-style code highlighting theme by default (new v2.0!)
-  - Built in table of contents generation from Markdown headings, now fully customizable by replacing the `{{> toc}}` partial in custom layout (new in 2.0!).
-  - Automatically detects the document title from the first heading in the Markdown markup (new in 2.0!)
-- Easier to get started with a custom layout via `--exports`, which exports a built in layout as a starting point for your custom layout (new in 2.0).
+- Metadata support: Each file can include additional metadata in a header section, such as the page title and author name which can then be used in the layout.
+
+### Layout features
+
+- Built in support for code syntax highlighting via highlight.js; all layouts include a Github-style code highlighting theme by default.
+- Built in table of contents generation from Markdown headings, fully customizable by replacing the `{{> toc}}` partial in custom layout.
+- Built in header id and anchor generation for headings written in Markdown; all layouts support revealing the URL via header hover links.
+- Support for custom logic for rendering code blocks via `--highlight-*`; this can be used to implement custom blocks that render the content of the code block in some interesting way.
+- Automatically detects the document title from the first heading in the Markdown markup.
+
+### Features for creating your own layout
+
+- To make it easier to get started, you can export an existing layout using `--exports` and use that as a starting point for your layouts.
 - Create your own layout based on an existing layout via `--layout` with:
-  - Full [Handlebars](http://handlebarsjs.com/) support for layouts, helpers and partials (new in 2.0!)
-  - Fully customizable table of contents template via the `toc` partial (new in 2.0!)
+  - Full [Handlebars](http://handlebarsjs.com/) support for layouts, helpers and partials
+  - Fully customizable table of contents template via the `toc` partial
   - Support for relative path generation via the `{{asset 'path'}}` helper
-- API support: `markdown-styles` now has a public API (new in 2.0!)
-- Changes in 2.0:
-  - Deprecated `--command`, `{{styles}}`, `--template`, `--asset-dir`, `--partials`, `--helpers`, `--runner`. Most of this functionality can be easily replicated much more cleanly with the new features.
-  - Improved highlighter support. Every built in layout now includes a default highlight.js CSS stylesheet and you no longer need to add extra CLI options to enable highlighting.
-  - Layout partials and helpers have been renamed: `{{content}}` -> `{{> content}}`, `{{toc}}` -> `{{> toc}}`, `{{assetsRelative}}` -> `{{asset 'path'}}`
-  - The default layout is now `github`, which looks a lot like Github readmes.
+- API support: `markdown-styles` now has a public API
 
+For changes, see [the changelog](changelog.md).
 
@@ -58,3 +61,3 @@ -----
   - The name of a builtin layout, such as `github` or `mixu-page`.
-  - A path to a layout folder (full path, or path relative to `process.cwd`).
+  - A path to a layout folder (full path, or a path relative to `process.cwd`).
   - A layout folder consists of:
@@ -65,10 +68,12 @@ - `./page.html`, the template to use in the layout
     - `./helpers`, the [helpers](#helpers) directory
-  - Note that `--template`, `--asset-dir`, `--partials` and `--helpers` are deprecated. This simplifies the loading logic. You need to put each of those resources in the same layout folder.
 - `--export <name>`: Exports a built-in layout to a directory. Use `--output <path>` to specify the location to write the built-in layout. For example, `--export github --output ./custom-layout` will copy the `github` builtin layout to `./custom-layout`.
 - `--highlight-<language> <module>`: Specifies a custom highlighter module to use for a specific language. For example, `--highlight-csv mds-csv` will highlight any `csv` code blocks using the `mds-csv` module.
+- `--no-header-links`: If this flag is passed, the HTML for header links will not be generated. The hover links are enabled by default.
 
 ## The resulting output
 
-The output HTML is fully static and uses relative paths to the asset files, which are also copied into the output folder. This means that you could, for example, point a HTTP server at the root of `./test/` and be done with it or push the output folder to Amazon S3.
+The output HTML is fully static and uses relative paths to the asset files, which are also copied into the output folder. This means that you could, for example, point a HTTP server at the output folder and be done with it or push the output folder to Amazon S3.
 
+For example, here is how I deploy one of my books: `aws s3 sync ./output/ s3://some-s3-bucket/some-folder/ --delete --exclude "node_modules/*"  --exclude ".git"` (assuming credentials are in the necessary environment variables and that the AWS CLI is installed).
+
 ## Syntax highlighting
@@ -99,4 +104,8 @@
 
-The `{{~> toc}}` partial generates a table of contents list. The list contains links to every header in your Markdown file. In addition, every Markdown header is automatically converted to a linkable anchor (e.g. `#table_of_contents`) when the page is generated. You can customize the table of contents markup by overriding the ./partials/[toc.hbs](https://github.com/mixu/markdown-styles/blob/master/builtin/partials/toc.hbs) partial in your custom layout.
+The `{{~> toc}}` partial generates a table of contents list. The list contains links to every header in your Markdown file. In addition, every Markdown header is automatically converted to a linkable anchor (e.g. `#table_of_contents`) when the page is generated. You can customize the table of contents markup by overriding the [./partials/toc.hbs](https://github.com/mixu/markdown-styles/blob/master/builtin/partials/toc.hbs) partial in your custom layout.
 
+## Header hover links (v2.1)
+
+If you are reading this on Github, hover over the header above. You'll see a link appear on the side of the header. The same feature is supported by all of the layouts. The feature is implemented purely with CSS, and you can find the details in `pilcrow.css` in each layout's assets folder. To disable the feature, pass the `--no-header-links` flag.
+
 ## Metadata sections
@@ -113,3 +122,3 @@
 
-There must be at least three - characters that separate the header from the rest of the content (on a single line).
+There must be at least three `-` characters that separate the header from the rest of the content (on a single line).
 
@@ -176,3 +185,3 @@ You can reference the metadata values in your template by name. The default layouts only make use of the `{{title}}` metadata value, but your custom layouts can refer to any additional fields you want.
 - `{{~> content}}`: renders the markdown content
-- `{{asset 'asset-path'}}`: renders a specific asset path (previously `{{assetsRelative}}` / `{{styles}}`)
+- `{{asset 'asset-path'}}`: renders a specific asset path
 - `{{~> toc}}`: renders the table of contents
@@ -284,2 +293,4 @@ - `{{title}}`: renders the title from the metadata section
 
+I'd like to thank @AaronJan for contributing a patch that adds support for Windows (for `v.2.2.0`+).
+
 I'd like to thank the following people for either contributing to markdown-styles directly or making CSS stylesheets available with a permissive open source license:
@@ -286,0 +297,0 @@

No alert changes

Improved metrics

Total package byte prevSize

2221879

increased by0.74%

Number of package files

139

increased by14.88%

Lines of code

33361

increased by2.06%

Number of lines in readme file

396

increased by2.86%

Dependency changes

• + Addedesprima@2.7.3(transitive)

• + Addedhighlight.js@8.8.0(transitive)

• + Addedinherit@2.2.7(transitive)

• + Addedjs-yaml@3.4.6(transitive)

• + Addedmarkdown-stream-utils@1.1.2(transitive)

• + Addedminimist@1.2.8(transitive)

• + Addedmkdirp@0.5.6(transitive)

• - Removedesprima@2.0.0(transitive)

• - Removedhighlight.js@8.4.0(transitive)

• - Removedjs-yaml@3.2.7(transitive)

• - Removedmarkdown-stream-utils@1.0.2(transitive)

• - Removedmkdirp@0.3.5(transitive)

• Updatedmarkdown-stream-utils@~1.1.0

• Updatedmkdirp@~0.5.1