{"id":13788548,"url":"https://github.com/fegemo/bespoke-markdownit","last_synced_at":"2025-05-12T03:30:27.754Z","repository":{"id":19962803,"uuid":"23229723","full_name":"fegemo/bespoke-markdownit","owner":"fegemo","description":"Allows using Markdown for bespoke.js presentation slides by leveraging markdown-it","archived":false,"fork":true,"pushed_at":"2021-04-26T20:32:40.000Z","size":5219,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-11T21:14:50.818Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://fegemo.github.io/bespoke-markdownit/","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"aaronpowell/bespoke-markdown","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fegemo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-08-22T15:16:28.000Z","updated_at":"2021-04-26T20:32:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fegemo/bespoke-markdownit","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fegemo%2Fbespoke-markdownit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fegemo%2Fbespoke-markdownit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fegemo%2Fbespoke-markdownit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fegemo%2Fbespoke-markdownit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fegemo","download_url":"https://codeload.github.com/fegemo/bespoke-markdownit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253639591,"owners_count":21940446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T21:00:49.910Z","updated_at":"2025-05-12T03:30:26.541Z","avatar_url":"https://github.com/fegemo.png","language":"JavaScript","readme":"[![Build Status](https://travis-ci.org/fegemo/bespoke-markdownit.svg?branch=master)](https://travis-ci.org/fegemo/bespoke-markdownit) [![Coverage Status](https://coveralls.io/repos/github/fegemo/bespoke-markdownit/badge.svg?branch=master)](https://coveralls.io/github/fegemo/bespoke-markdownit?branch=master)\n\n# bespoke-markdownit\n\nAllows you to use [(GitHub flavored) Markdown][gfm] to author your [bespoke.js](https://github.com/markdalgleish/bespoke.js) presentation.\nThere are 4 ways to use this plugin and they are described on the [demo page](http://fegemo.github.io/bespoke-markdownit/).\n\n[gfm]: https://help.github.com/articles/github-flavored-markdown\n\nbespoke-markdownit renders Markdown in HTML using the awesome\n[markdown-it][markdown-it] parser.\n\n## Download\n\nDownload the [production version][min] or the [development version][max],\nor use a [package manager](#package-managers).\n\n[min]: https://raw.github.com/fegemo/bespoke-markdown/master/dist/bespoke-markdownit.min.js\n[max]: https://raw.github.com/fegemo/bespoke-markdown/master/dist/bespoke-markdownit.js\n\n## Usage\n\nThere are 3 steps to using this plugin.\n  1. Including and initializing the plugin\n  1. Including a stylesheet for code highlighting\n  1. Authoring the presentation using Markdown\n\n\n### 1. Including and initializing the plugin\n\nThis plugin is shipped in a [UMD format](https://github.com/umdjs/umd),\nmeaning that it is available as a CommonJS/AMD module or browser global.\n\nFor example, when using CommonJS modules:\n\n```js\nconst bespoke = require('bespoke'),\n  markdown = require('bespoke-markdownit');\n\nbespoke.from('#presentation', [\n  markdown()\n]);\n```\n\nIf using browser globals:\n\n```js\nbespoke.from('#presentation', [\n  bespoke.plugins.markdownIt()\n]);\n```\n\n#### Plugin Options\n\nThe plugin builder accepts up to 2 parameters for configuration.\nThe first allows the **definition of metadata for each slide**. That data can\nbe used by callbacks provided to the plugin builder function. The second\nparameter allows **passing plugins to the markdown-it** parser. There are\nvarious [markdown-it plugins][plugins], such as one to extend the Markdown\nsyntax to allow `\u003cabbr\u003e\u003c/abbr\u003e` ([markdown-it-abbr][plugin-abbr]).\n\nLet us see how to use both parameters.\n\n##### 1st parameter: Slide metadata\n\nThe first parameter, if defined, is a object whose keys are names of\nfunctions and values are callbacks to be invoked when certain Markdown\nslides are parsed.\n\nFor example, if we want to add some class to a specific Markdown slide, we\ncan add metadata to that slide with the name of the class it should have and\nprovide a function to the plugin builder that just adds a class to the\nslide owner of the metadata. The Markdown file would look like:\n\n```markdown\n# First slide\n---\n\u003c!--\n{\n  \"addClassToSlide\": \"2-columns-slide-layout\"\n}\n--\u003e\n# Second slide\n\n![](image-left-side.png)\n![](image-right-side.png)\n---\n# Third slide\n```\n\nThen, we need to provide a property called `addClassToSlide` which contains\na callback that effectively adds a class to the slide:\n\n```js\nbespoke.from('#presentation',\n  markdown({\n    // slideEl is the HTMLElement of the slide (it is always provided\n    //   as the first argument)\n    // className is the value defined as the metadata. It could be any\n    //   JSON value\n    addClassToSlide: function(slideEl, className) {\n      slideEl.classList.push(className);\n    },\n    // another metadata callback function that can be called\n    logThisMessage: function(slideEl, message) {\n      console.log(message);\n    }\n  })\n);\n```\n\nThe example would result in the following HTML:\n\n```html\n\u003carticle id=\"presentation\"\u003e\n  \u003csection\u003e\n    \u003ch1\u003eFirst Slide\u003c/h1\u003e\n  \u003c/section\u003e\n  \u003csection class=\"2-columns-slide-layout\"\u003e\n    \u003ch1\u003eSecond Slide\u003c/h1\u003e\n    \u003cimg src=\"image-left-side.png\" alt=\"\"\u003e\n    \u003cimg src=\"image-right-side.png\" alt=\"\"\u003e\n  \u003c/section\u003e\n  \u003csection\u003e\n    \u003ch1\u003eThird Slide\u003c/h1\u003e\n  \u003c/section\u003e\n\u003c/article\u003e\n```\n\nThe **metadata must be defined as an HTML comment** as the **first\nthing in a slide** (i.e., right after the `---`, on a new line). Besides,\n**its content must be a valid JSON string**, otherwise the comment will\njust be ignored by the bespoke-markdownit plugin (in fact, we\n  use `JSON.parse()` on the comment node value).\n\nIt is possible to call various callback functions from the metadata by\nproviding multiple keys, as in the following example.\n\n```markdown\n\u003c!--\n{\n  \"addClassToSlide\": \"pinky\",\n  \"logThisMessage\": \"yayyyyy\"\n}\n--\u003e\n# First Slide\n```\n\nAdditionally, if a value is passed as an array or an object, the\ncallback function will receive it proper, such as illustrated.\n\n```markdown\n\u003c!--\n{\n  \"injectStylesheets\": [\"main.css\", \"ribbon.css\"]\n}\n--\u003e\n```\n\nAnd on the plugin builder function:\n\n```js\nbespoke.from('#presentation',\n  markdown({\n    injectStylesheets: function(slideEl, fileNames) {\n      fileNames = Array.isArray(fileName) ? fileNames : [fileNames];\n      fileNames.forEach(name =\u003e {\n        const sheet = document.createElement('link');\n        sheet.setAttribute('rel', 'stylesheet');\n        sheet.setAttribute('href', name);\n        slideEl.appendChild(sheet);        \n      });\n    }\n  })\n);\n```\n\n##### 2nd parameter: markdown-it plugins\n\nThe second parameter allows passing markdown-it plugins to the\nmarkdown-it parser. If provided, it should be **an array of plugin\nbuilder functions**, such as in the following example.\n\n```js\n// ...\nconst abbrPlugin = require('markdown-it-abbr');\nconst decoratePlugin = require('markdown-it-decorate');\nbespoke.from('#presentation',\n  markdown(\n    // the first argument must be supplied, even if not using metadata\n    {},\n    // an array of plugin builder functions\n    [abbrPlugin, decoratePlugin]\n  )\n);\n```\n\nThe order in which they are passed to the bespoke-markdownit builder is the\nsame that it passes along to markdown-it.\n\n### 2. Stylesheet for code highlighting\n\nIf you want code highlighting, you also need to include a stylesheet from\n[highlight.js][hljs], which is the package used by this plugin. One option\nto include it is via the dependencies of this plugin, as highlight.js is a\ndependency of bespoke-markdownit.\n\nIn that case, you can include it by:\n\n```html\n\u003clink rel=\"stylesheet\" type=\"text/css\" href=\"node_modules/highlight.js/styles/THEME_NAME.css\" /\u003e\n```\n\nYou can choose [any theme][th] from highlight.js and put it instead of\n`THEME_NAME`. Some themes are:\n  - default.css\n  - monokai-sublime.css\n  - sublime.css\n  - github.css\n\n[th]: https://highlightjs.org/static/test.html\n\n\n### 3. Authoring presentation using Markdown\n\nJust by including the plugin code and initializing bespoke with it will **allow\nwriting the content of the slides in Markdown**. You can use a markup similar to\nthe following:\n\n```html\n\u003carticle\u003e\n  \u003csection\u003e\n# Title\nThis is **markdown content**.\n  \u003c/section\u003e\n\u003c/article\u003e\n```\n\nYou can also write Markdown content in external files. You can do it for the\nwhole presentation or for specific slides. To mark a slide to be rendered using\nMarkdown, you need to add the `data-markdown=\"path-to-file.md\"` attribute to the\npresentation HTML element, like so:\n\n```html\n\u003carticle data-markdown=\"presentation.md\"\u003e\u003c/article\u003e\n```\n\nOr, you can add it to specific slides only:\n```html\n\u003carticle\u003e\n  \u003csection data-markdown=\"slide-1.md\"\u003e\u003c/section\u003e\n  \u003csection\u003e\n    \u003cp\u003eA slide authored in HTML\u003c/p\u003e\n  \u003c/section\u003e\n  \u003csection data-markdown=\"slide-3.md\"\u003e\u003c/section\u003e\n\u003c/article\u003e\n```\n\nYou can split the `.md` file in multiple slides by using \"`---`\" to separate\nthem. For instance, `presentation.md`:\n\n```markdown\nThis is the first slide\n---\nSecond slide\n---\nAnd third!\n```\n\nAdditionally, you can mix slides authored in HTML and in Markdown. To mark a\nslide to have its contents rendered as Markdown, we also use the `data-markdown`\nattribute, but without a value (or with an empty value, i.e.,\n`data-markdown=\"\"`). Check the example:\n```html\n\u003carticle\u003e\n  \u003csection data-markdown\u003e\n    # Title 1\n    This is a slide authored in Markdown.\n  \u003c/section\u003e\n  \u003csection data-markdown=\"\"\u003e\n    # Title 2\n    This is also a slide authored in Markdown.\n  \u003c/section\u003e\n  \u003csection\u003e\n    \u003ch1\u003eTitle 3\u003c/h1\u003e\n    \u003cp\u003eThis is a slide authored in HTML.\u003c/p\u003e\n  \u003c/section\u003e\n\u003c/article\u003e\n```\n\n## Package managers\n\n### npm\n\n```bash\n$ npm install bespoke-markdownit\n```\n\n## History and Motivation\n\nbespoke-markdownit was forked from [bespoke-markdown][bespoke-markdown] and is\nalso inspired by [bespoke-meta-markdown][bespoke-meta-markdown].\n\nbespoke-markdown uses [marked][marked] as its parser, which bespoke-markdownit\nimproves by using [markdown-it][markdown-it]. The latter is not as fast as\n[marked][marked], but it was designed to be extensible through plugins\nfrom the beggining and, as such, is much more flexible.\n\nbespoke-meta-markdown is, in turn, a fork of bespoke-markdown that allows\nthe definition of slide metadata inside HTML comments but in the YAML format.\nFor so, it has a larger signature than this plugin as it has to include a\nYAML parser.\n\n## Credits\n\nThis plugin was built with\n[generator-bespokeplugin](https://github.com/markdalgleish/generator-bespokeplugin).\n\n## License\n\n[MIT License](http://en.wikipedia.org/wiki/MIT_License)\n\n[markdown-it]: https://github.com/markdown-it/markdown-it\n[plugins]: https://www.npmjs.com/browse/keyword/markdown-it-plugin\n[plugin-abbr]: https://github.com/markdown-it/markdown-it-abbr\n[hljs]: https://highlightjs.org/\n[bespoke-markdown]: https://github.com/aaronpowell/bespoke-markdown\n[bespoke-meta-markdown]: https://github.com/davidmarkclements/bespoke-meta-markdown\n[marked]: https://github.com/chjj/marked\n","funding_links":[],"categories":["Uncategorized","Presentation"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffegemo%2Fbespoke-markdownit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffegemo%2Fbespoke-markdownit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffegemo%2Fbespoke-markdownit/lists"}