|
| 1 | +import {MarkedOptions, Renderer} from 'marked'; |
| 2 | +import {basename, extname} from 'path'; |
| 3 | +import {highlightCodeBlock} from './highlight-code-block'; |
| 4 | + |
| 5 | +/** Regular expression that matches whitespace. */ |
| 6 | +const whitespaceRegex = /\W+/g; |
| 7 | + |
| 8 | +/** Regular expression that matches example comments. */ |
| 9 | +const exampleCommentRegex = /<!--\W*example\(([^)]+)\)\W*-->/g; |
| 10 | + |
| 11 | +/** |
| 12 | + * Custom renderer for marked that will be used to transform markdown files to HTML |
| 13 | + * files that can be used in the Angular Material docs. |
| 14 | + */ |
| 15 | +export class DocsMarkdownRenderer extends Renderer { |
| 16 | + |
| 17 | + constructor(options?: MarkedOptions) { |
| 18 | + super({highlight: highlightCodeBlock, baseUrl: 'material.angular.io/', ...options}); |
| 19 | + } |
| 20 | + |
| 21 | + /** |
| 22 | + * Transforms a markdown heading into the corresponding HTML output. In our case, we |
| 23 | + * want to create a header-link for each H3 and H4 heading. This allows users to jump to |
| 24 | + * specific parts of the docs. |
| 25 | + */ |
| 26 | + heading(label: string, level: number, _raw: string) { |
| 27 | + if (level === 3 || level === 4) { |
| 28 | + const headingId = label.toLowerCase().replace(whitespaceRegex, '-'); |
| 29 | + |
| 30 | + return ` |
| 31 | + <h${level} id="${headingId}" class="docs-header-link"> |
| 32 | + <span header-link="${headingId}"></span> |
| 33 | + ${label} |
| 34 | + </h${level}> |
| 35 | + `; |
| 36 | + } |
| 37 | + |
| 38 | + return `<h${level}>${label}</h${level}>`; |
| 39 | + } |
| 40 | + |
| 41 | + /** Transforms markdown links into the corresponding HTML output. */ |
| 42 | + link(href: string, title: string, text: string) { |
| 43 | + // We only want to fix up markdown links that are relative and do not refer to guides already. |
| 44 | + // Otherwise we always map the link to the "guide/" path. |
| 45 | + // TODO(devversion): remove this logic and just disallow relative paths. |
| 46 | + if (!href.startsWith('http') && !href.includes('guide/')) { |
| 47 | + return super.link(`guide/${basename(href, extname(href))}`, title, text); |
| 48 | + } |
| 49 | + |
| 50 | + return super.link(href, title, text); |
| 51 | + } |
| 52 | + |
| 53 | + /** |
| 54 | + * Method that will be called whenever inline HTML is processed by marked. In that case, |
| 55 | + * we can easily transform the example comments into real HTML elements. For example: |
| 56 | + * |
| 57 | + * `<!-- example(name) -->` turns into `<div material-docs-example="name"></div>` |
| 58 | + */ |
| 59 | + html(html: string) { |
| 60 | + html = html.replace(exampleCommentRegex, (_match: string, name: string) => |
| 61 | + `<div material-docs-example="${name}"></div>` |
| 62 | + ); |
| 63 | + |
| 64 | + return super.html(html); |
| 65 | + } |
| 66 | + |
| 67 | + /** |
| 68 | + * Method that will be called after a markdown file has been transformed to HTML. This method |
| 69 | + * can be used to finalize the content (e.g. by adding an additional wrapper HTML element) |
| 70 | + */ |
| 71 | + finalizeOutput(output: string): string { |
| 72 | + return `<div class="docs-markdown">${output}</div>`; |
| 73 | + } |
| 74 | +} |
0 commit comments