feat: added capability to add css class and id to images + links + refactoring (docsifyjs#820)

* method extraction

* support for CSS class and id

* Update package.json

* Added tests for refactored render-methods

* minor refactoring

Author: arelstone

cypress/integration/sidebar/config.spec.js

@@ -239,7 +239,6 @@ context('sidebar.configurations', () => {
     'set-target-attribute-for-link',
     'disable-link',
     'github-task-lists',
-    'image-resizing',
     'customise-id-for-headings',
     'markdown-in-html-tag'
   ]

cypress/snapshots/sidebar/config.spec.js/sidebar.configurations -- go to #helpersid=image-resizing.snap.png

@@ -81,9 +81,12 @@ You will get `<a href="/demo/">link</a>`html. Do not worry, you can still set ti
   - [ ] bim
   - [ ] lim
 
-## Image resizing
+## Image
+
+### Resizing
 
 ```md
+![logo](https://docsify.js.org/_media/icon.svg ':size=WIDTHxHEIGHT')
 ![logo](https://docsify.js.org/_media/icon.svg ':size=50x100')
 ![logo](https://docsify.js.org/_media/icon.svg ':size=100')
 
@@ -96,6 +99,18 @@ You will get `<a href="/demo/">link</a>`html. Do not worry, you can still set ti
 ![logo](https://docsify.js.org/_media/icon.svg ':size=100')
 ![logo](https://docsify.js.org/_media/icon.svg ':size=10%')
 
+### Customise class
+
+```md
+![logo](https://docsify.js.org/_media/icon.svg ':class=someCssClass')
+```
+
+### Customise ID
+
+```md
+![logo](https://docsify.js.org/_media/icon.svg ':id=someCssId')
+```
+
 ## Customise ID for headings
 
 ```md

docs/helpers.md

@@ -1,14 +1,16 @@
-import marked from 'marked'
-import Prism from 'prismjs'
-import { helper as helperTpl, tree as treeTpl } from './tpl'
+import { tree as treeTpl } from './tpl'
 import { genTree } from './gen-tree'
 import { slugify } from './slugify'
 import { emojify } from './emojify'
 import { isAbsolutePath, getPath, getParentPath } from '../router/util'
 import { isFn, merge, cached, isPrimitive } from '../util/core'
-
-// See https://github.com/PrismJS/prism/pull/1367
-import 'prismjs/components/prism-markup-templating'
+import { imageCompiler } from './compiler/image'
+import { highlightCodeCompiler } from './compiler/code'
+import { paragraphCompiler } from './compiler/paragraph'
+import { taskListCompiler } from './compiler/taskList'
+import { taskListItemCompiler } from './compiler/taskListItem'
+import { linkCompiler } from './compiler/link'
+import marked from 'marked'
 
 const cachedLinks = {}
 
@@ -189,7 +191,7 @@ export class Compiler {
 
   _initRenderer() {
     const renderer = new marked.Renderer()
-    const { linkTarget, linkRel, router, contentBase } = this
+    const { linkTarget, router, contentBase } = this
     const _self = this
     const origin = {}
 
@@ -224,117 +226,12 @@ export class Compiler {
       return `<h${level} id="${slug}"><a href="${url}" data-id="${slug}" class="anchor"><span>${str}</span></a></h${level}>`
     }
 
-    // Highlight code
-    origin.code = renderer.code = function (code, lang = '') {
-      code = code.replace(/@DOCSIFY_QM@/g, '`')
-      const hl = Prism.highlight(
-        code,
-        Prism.languages[lang] || Prism.languages.markup
-      )
-
-      return `<pre v-pre data-lang="${lang}"><code class="lang-${lang}">${hl}</code></pre>`
-    }
-
-    origin.link = renderer.link = function (href, title = '', text) {
-      let attrs = ''
-
-      const { str, config } = getAndRemoveConfig(title)
-      title = str
-
-      if (
-        !isAbsolutePath(href) &&
-        !_self._matchNotCompileLink(href) &&
-        !config.ignore
-      ) {
-        if (href === _self.config.homepage) {
-          href = 'README'
-        }
-
-        href = router.toURL(href, null, router.getCurrentPath())
-      } else {
-        attrs += href.indexOf('mailto:') === 0 ? '' : ` target="${linkTarget}"`
-        attrs += href.indexOf('mailto:') === 0 ? '' : (linkRel !== '' ? ` rel="${linkRel}"` : '')
-      }
-
-      if (config.target) {
-        attrs += ' target=' + config.target
-      }
-
-      if (config.disabled) {
-        attrs += ' disabled'
-        href = 'javascript:void(0)'
-      }
-
-      if (title) {
-        attrs += ` title="${title}"`
-      }
-
-      return `<a href="${href}"${attrs}>${text}</a>`
-    }
-
-    origin.paragraph = renderer.paragraph = function (text) {
-      let result
-      if (/^!&gt;/.test(text)) {
-        result = helperTpl('tip', text)
-      } else if (/^\?&gt;/.test(text)) {
-        result = helperTpl('warn', text)
-      } else {
-        result = `<p>${text}</p>`
-      }
-
-      return result
-    }
-
-    origin.image = renderer.image = function (href, title, text) {
-      let url = href
-      let attrs = ''
-
-      const { str, config } = getAndRemoveConfig(title)
-      title = str
-
-      if (config['no-zoom']) {
-        attrs += ' data-no-zoom'
-      }
-
-      if (title) {
-        attrs += ` title="${title}"`
-      }
-
-      const size = config.size
-      if (size) {
-        const sizes = size.split('x')
-        if (sizes[1]) {
-          attrs += 'width=' + sizes[0] + ' height=' + sizes[1]
-        } else {
-          attrs += 'width=' + sizes[0]
-        }
-      }
-
-      if (!isAbsolutePath(href)) {
-        url = getPath(contentBase, getParentPath(router.getCurrentPath()), href)
-      }
-
-      return `<img src="${url}"data-origin="${href}" alt="${text}"${attrs}>`
-    }
-
-    origin.list = renderer.list = function (body, ordered, start) {
-      const isTaskList = /<li class="task-list-item">/.test(body.split('class="task-list"')[0])
-      const isStartReq = start && start > 1
-      const tag = ordered ? 'ol' : 'ul'
-      const tagAttrs = [
-        (isTaskList ? 'class="task-list"' : ''),
-        (isStartReq ? `start="${start}"` : '')
-      ].join(' ').trim()
-
-      return `<${tag} ${tagAttrs}>${body}</${tag}>`
-    }
-
-    origin.listitem = renderer.listitem = function (text) {
-      const isTaskItem = /^(<input.*type="checkbox"[^>]*>)/.test(text)
-      const html = isTaskItem ? `<li class="task-list-item"><label>${text}</label></li>` : `<li>${text}</li>`
-
-      return html
-    }
+    origin.code = highlightCodeCompiler({ renderer })
+    origin.link = linkCompiler({ renderer, router, linkTarget, compilerClass: _self })
+    origin.paragraph = paragraphCompiler({ renderer })
+    origin.image = imageCompiler({ renderer, contentBase, router })
+    origin.list = taskListCompiler({ renderer })
+    origin.listitem = taskListItemCompiler({ renderer })
 
     renderer.origin = origin
 

package-lock.json

@@ -0,0 +1,10 @@
+import Prism from 'prismjs'
+// See https://github.com/PrismJS/prism/pull/1367
+import 'prismjs/components/prism-markup-templating'
+
+export const highlightCodeCompiler = ({ renderer }) => renderer.code = function (code, lang = '') {
+  const langOrMarkup = Prism.languages[lang] || Prism.languages.markup
+  const text = Prism.highlight(code.replace(/@DOCSIFY_QM@/g, '`'), langOrMarkup)
+
+  return `<pre v-pre data-lang="${lang}"><code class="lang-${lang}">${text}</code></pre>`
+}

packages/docsify-server-renderer/package-lock.json

@@ -0,0 +1,27 @@
+
+import { getAndRemoveConfig } from '../compiler'
+import { slugify } from './slugify'
+
+export const headingCompiler = ({ renderer, router, _self }) => renderer.code = (text, level) => {
+  let { str, config } = getAndRemoveConfig(text)
+  const nextToc = { level, title: str }
+
+  if (/{docsify-ignore}/g.test(str)) {
+    str = str.replace('{docsify-ignore}', '')
+    nextToc.title = str
+    nextToc.ignoreSubHeading = true
+  }
+
+  if (/{docsify-ignore-all}/g.test(str)) {
+    str = str.replace('{docsify-ignore-all}', '')
+    nextToc.title = str
+    nextToc.ignoreAllSubs = true
+  }
+
+  const slug = slugify(config.id || str)
+  const url = router.toURL(router.getCurrentPath(), { id: slug })
+  nextToc.slug = url
+  _self.toc.push(nextToc)
+
+  return `<h${level} id="${slug}"><a href="${url}" data-id="${slug}" class="anchor"><span>${str}</span></a></h${level}>`
+}

src/core/render/compiler.js

@@ -0,0 +1,42 @@
+import { getAndRemoveConfig } from '../compiler'
+import { isAbsolutePath, getPath, getParentPath } from '../../router/util'
+
+export const imageCompiler = ({ renderer, contentBase, router }) => renderer.image = (href, title, text) => {
+  let url = href
+  let attrs = []
+
+  const { str, config } = getAndRemoveConfig(title)
+  title = str
+
+  if (config['no-zoom']) {
+    attrs.push('data-no-zoom')
+  }
+
+  if (title) {
+    attrs.push(`title="${title}"`)
+  }
+
+  if (config.size) {
+    const [width, height] = config.size.split('x')
+    if (height) {
+      attrs.push(`width="${width}" height="${height}"`)
+    } else {
+      attrs.push(`width="${width}" height="${width}"`)
+    }
+  }
+
+  if (config.class) {
+    attrs.push(`class="${config.class}"`)
+  }
+
+  if (config.id) {
+    attrs.push(`id="${config.id}"`)
+  }
+
+  if (!isAbsolutePath(href)) {
+    url = getPath(contentBase, getParentPath(router.getCurrentPath()), href)
+  }
+
+  return `<img src="${url}" data-origin="${href}" alt="${text}" ${attrs.join(' ')} />`
+}
+

src/core/render/compiler/code.js

@@ -0,0 +1,42 @@
+import { getAndRemoveConfig } from '../compiler'
+import { isAbsolutePath } from '../../router/util'
+
+export const linkCompiler = ({ renderer, router, linkTarget, compilerClass }) => renderer.link = (href, title = '', text) => {
+  let attrs = []
+  const { str, config } = getAndRemoveConfig(title)
+
+  title = str
+
+  if (!isAbsolutePath(href) && !compilerClass._matchNotCompileLink(href) && !config.ignore) {
+    if (href === compilerClass.config.homepage) {
+      href = 'README'
+    }
+
+    href = router.toURL(href, null, router.getCurrentPath())
+  } else {
+    attrs.push(href.indexOf('mailto:') === 0 ? '' : `target="${linkTarget}"`)
+  }
+
+  if (config.target) {
+    attrs.push(`target="${config.target}"`)
+  }
+
+  if (config.disabled) {
+    attrs.push('disabled')
+    href = 'javascript:void(0)'
+  }
+
+  if (config.class) {
+    attrs.push(`class="${config.class}"`)
+  }
+
+  if (config.id) {
+    attrs.push(`id="${config.id}"`)
+  }
+
+  if (title) {
+    attrs.push(`title="${title}"`)
+  }
+
+  return `<a href="${href}" ${attrs.join(' ')}>${text}</a>`
+}

src/core/render/compiler/headline.js

@@ -0,0 +1,15 @@
+import { helper as helperTpl } from '../tpl'
+
+export const paragraphCompiler = ({ renderer }) => renderer.paragraph = text => {
+  let result
+  if (/^!>/.test(text)) {
+    result = helperTpl('tip', text)
+  } else if (/^\?>/.test(text)) {
+    result = helperTpl('warn', text)
+  } else {
+    result = `<p>${text}</p>`
+  }
+
+  return result
+}
+

src/core/render/compiler/image.js

@@ -0,0 +1,13 @@
+export const taskListCompiler = ({renderer}) => renderer.list = (body, ordered, start) => {
+  const isTaskList = /<li class="task-list-item">/.test(body.split('class="task-list"')[0])
+  const isStartReq = start && start > 1
+  const tag = ordered ? 'ol' : 'ul'
+  const tagAttrs = [
+    (isTaskList ? 'class="task-list"' : ''),
+    (isStartReq ? `start="${start}"` : '')
+  ]
+    .join(' ')
+    .trim()
+
+  return `<${tag} ${tagAttrs}>${body}</${tag}>`
+}

src/core/render/compiler/link.js

@@ -0,0 +1,6 @@
+export const taskListItemCompiler = ({ renderer }) => renderer.listitem = text => {
+  const isTaskItem = /^(<input.*type="checkbox"[^>]*>)/.test(text)
+  const html = isTaskItem ? `<li class="task-list-item"><label>${text}</label></li>` : `<li>${text}</li>`
+
+  return html
+}

src/core/render/compiler/paragraph.js

@@ -40,7 +40,7 @@ describe('render', function () {
 - [linktext](link)
 - just text`)
       expectSameDom(output, `<ul >
-				<li><a href="#/link">linktext</a></li>
+				<li><a href="#/link" >linktext</a></li>
 				<li>just text</li>
 			</ul>`)
     })
@@ -83,4 +83,155 @@ text
 			</ul>`)
     })
   })
+
+  describe('image', function () {
+    it('regular', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('![alt text](http://imageUrl)')
+
+      expectSameDom(output, '<p><img src="http://imageUrl" data-origin="http://imageUrl" alt="alt text"  /></p>')
+    })
+
+    it('class', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('![alt text](http://imageUrl \':class=someCssClass\')')
+
+      expectSameDom(output, '<p><img src="http://imageUrl" data-origin="http://imageUrl" alt="alt text" class="someCssClass" /></p>')
+    })
+
+    it('id', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('![alt text](http://imageUrl \':id=someCssID\')')
+
+      expectSameDom(output, '<p><img src="http://imageUrl" data-origin="http://imageUrl" alt="alt text" id="someCssID" /></p>')
+    })
+
+    it('no-zoom', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('![alt text](http://imageUrl \':no-zoom\')')
+
+      expectSameDom(output, '<p><img src="http://imageUrl" data-origin="http://imageUrl" alt="alt text" data-no-zoom /></p>')
+    })
+
+    describe('size', function () {
+      it('width and height', async function () {
+        const { docsify } = await init()
+        const output = docsify.compiler.compile('![alt text](http://imageUrl \':size=WIDTHxHEIGHT\')')
+
+        expectSameDom(output, '<p><img src="http://imageUrl" data-origin="http://imageUrl" alt="alt text" width="WIDTH" height="HEIGHT" /></p>')
+      })
+
+      it('width', async function () {
+        const { docsify } = await init()
+        const output = docsify.compiler.compile('![alt text](http://imageUrl \':size=50\')')
+
+        expectSameDom(output, '<p><img src="http://imageUrl" data-origin="http://imageUrl" alt="alt text" width="50" height="50" /></p>')
+      })
+    })
+  })
+
+  describe('heading', function () {
+    it('h1', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('# h1 tag')
+      expectSameDom(output, `
+      <h1 id="h1-tag">
+        <a href="#/?id=h1-tag" data-id="h1-tag" class="anchor">
+          <span>h1 tag</span>
+        </a>
+      </h1>`)
+    })
+
+    it('h2', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('## h2 tag')
+      expectSameDom(output, `
+      <h2 id="h2-tag">
+        <a href="#/?id=h2-tag" data-id="h2-tag" class="anchor">
+          <span>h2 tag</span>
+        </a>
+      </h2>`)
+    })
+
+    it('h3', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('### h3 tag')
+      expectSameDom(output, `
+      <h3 id="h3-tag">
+        <a href="#/?id=h3-tag" data-id="h3-tag" class="anchor">
+          <span>h3 tag</span>
+        </a>
+      </h3>`)
+    })
+
+    it('h4', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('#### h4 tag')
+      expectSameDom(output, `
+      <h4 id="h4-tag">
+        <a href="#/?id=h4-tag" data-id="h4-tag" class="anchor">
+          <span>h4 tag</span>
+        </a>
+      </h4>`)
+    })
+
+    it('h5', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('##### h5 tag')
+      expectSameDom(output, `
+      <h5 id="h5-tag">
+        <a href="#/?id=h5-tag" data-id="h5-tag" class="anchor">
+          <span>h5 tag</span>
+        </a>
+      </h5>`)
+    })
+
+    it('h6', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('###### h6 tag')
+      expectSameDom(output, `
+      <h6 id="h6-tag">
+        <a href="#/?id=h6-tag" data-id="h6-tag" class="anchor">
+          <span>h6 tag</span>
+        </a>
+      </h6>`)
+    })
+  })
+
+  describe('link', function () {
+    it('regular', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('[alt text](http://url)')
+
+      expectSameDom(output, '<p><a href="http://url" target="_blank">alt text</a></p>')
+    })
+
+    it('disabled', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('[alt text](http://url \':disabled\')')
+
+      expectSameDom(output, '<p><a href="javascript:void(0)" target="_blank" disabled>alt text</a></p>')
+    })
+
+    it('target', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('[alt text](http://url \':target=_self\')')
+
+      expectSameDom(output, '<p><a href="http://url" target="_blank" target="_self">alt text</a></p>')
+    })
+
+    it('class', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('[alt text](http://url \':class=someCssClass\')')
+
+      expectSameDom(output, '<p><a href="http://url" target="_blank" class="someCssClass">alt text</a></p>')
+    })
+
+    it('id', async function () {
+      const { docsify } = await init()
+      const output = docsify.compiler.compile('[alt text](http://url \':id=someCssID\')')
+
+      expectSameDom(output, '<p><a href="http://url" target="_blank" id="someCssID">alt text</a></p>')
+    })
+  })
 })