@skypager/runnable-mdx-example v1.4.2
Runnable MDX Example
This project contains an example web application which uses the @skypager/helpers-document to build a database of documents, and then display it as a website. We use the Runnable or Renderable components to render our markdown code blocks as special components that use Ace Editor to let the user edit the code block, and get immediate feedback when the code changes in the form of component examples or REPL like output with the results of each line.
TODO: Include Visual Example
You can launch the demo using the following
$ yarn demoTestable Markdown
Running the following command will give you just one potential application of having markdown documents which can run their code blocks.
$ skypager test-code-blocks README.md
Runnable MDX Code Blocks
As of MDX.js 1.0, we can pass additional props to our components for code blocks
This code block will be editable, and runnable:
~~~javascript runnable=true
const sum = 1 + 1
console.log('YO YO', sum)
~~~This will result in <Editor value="const sum = 1 + 1\nconsole.log('YO YO', sum)" runnable mode="javascript" />
Highlights
We can discover all of the mdx files in our project, process them, and make them runnable
const runtime = require('@skypager/node').use(require('@skypager/helpers-document'))
async function createRunnableDocs() {
await runtime.mdxDocs.discover()
const docs = runtime.mdxDocs.allInstances({ cacheHelper: true })
return Promise.all(
docs.map((doc) => doc.process()).then(() => doc.toRunnable())
)
return docs
}Convert Markdown blocks to a JavaScript Module
Once we have a runnable markdown document, we can convert it to a JavaScript module.
The module exports will consist of functions named after the parent headings the code block belong to.
const runnable = runtime.mdxDoc('README', { cacheHelper: true })
async function useRunnable() {
await runnable.process()
const runnableModule = await runnable.toExport()
return runnableModule
}
useRunnable().then((mod) => {
mod.should.have.property('highlights').that.is.a('function')
})How does it work
We can use the MDX AST to extract the language nouns and attributes are used in the writing.
When we're writing about software, we can take advantage of the importance of nouns and names as they usually refer to the things we're working on in our code.
We assume things about each noun based on the heading it belongs to. For example, the list items under the ## Sitemap heading contain links.
We assume the text of the link is the name of the page, and the href of the link is the URL that page is served on.
We assume links to certain types of files can be parsed and followed, and even understood by other Skypager Helpers. (Google Sheets, Google Docs, Sketch Files, can all be turned into objects with APIs.)
The SITE-TEMPLATE.md file is a Markdown document with YAML frontmatter.
---
projectType: react-web-application
customer: Soederpop, Inc
deployTo: zeit
accounts:
google: soederpops-google
---
# [My Website](https://soederpop.com)
[Sketchfile Link](https://link.to/designer/)
[Mock Data](https://google-sheets.com/my/spreadsheets/my-website/mock-data)
[Page Copy](https://google-docs/my/documents/my-website/content)
## Sitemap
- [Home](/)
- [About](/about)
- [Contact US](/contact-us)
- [Products](/products)
- [Product Details](/products/:id)The Document Helper uses MDX to turn this content it into the following:
async function main() {
await runtime.mdxDocs.discover()
const siteTemplate = runtime.mdxDoc('SITE-TEMPLATE')
const { meta, ast, headingsMap, Component } = siteTemplate
}headingsMap
{
"headings": {
"My Website": 1,
"Sitemap": 7
},
"lines": {
"1": "My Website",
"7": "Sitemap"
}
}Metadata
{
projectType: "react-web-application",
"customer": "Soederpop, Inc",
"deplyTo": "zeit",
"accounts": {
"google": "soederpops-google"
}
}AST
{
"type": "root",
"children": [
{
"type": "heading",
"depth": 1,
"children": [
{
"type": "link",
"title": null,
"url": "https://soederpop.com",
"children": [
{
"type": "text",
"value": "My Website"
}
]
}
],
"position": {
"start": {
"line": 2,
"column": 1,
"offset": 1
},
"end": {
"line": 2,
"column": 38,
"offset": 38
}
}
},
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "https://link.to/designer/",
"children": [
{
"type": "text",
"value": "Sketchfile Link"
}
]
},
{
"type": "text",
"value": "\n"
},
{
"type": "link",
"title": null,
"url": "https://google-sheets.com/my/spreadsheets/my-website/mock-data",
"children": [
{
"type": "text",
"value": "Mock Data"
}
]
},
{
"type": "text",
"value": "\n"
},
{
"type": "link",
"title": null,
"url": "https://google-docs/my/documents/my-website/content",
"children": [
{
"type": "text",
"value": "Page Copy"
}
]
}
],
"position": {
"start": {
"line": 4,
"column": 1,
"offset": 40
},
"end": {
"line": 6,
"column": 65,
"offset": 225
}
}
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Sitemap"
}
],
"position": {
"start": {
"line": 8,
"column": 1,
"offset": 227
},
"end": {
"line": 8,
"column": 12,
"offset": 238
}
}
},
{
"type": "list",
"ordered": false,
"start": null,
"loose": false,
"children": [
{
"type": "listItem",
"loose": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/",
"children": [
{
"type": "text",
"value": "Home"
}
]
}
]
}
]
},
{
"type": "listItem",
"loose": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/about",
"children": [
{
"type": "text",
"value": "About"
}
]
},
{
"type": "text",
"value": " "
}
]
}
]
},
{
"type": "listItem",
"loose": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/contact-us",
"children": [
{
"type": "text",
"value": "Contact US"
}
]
},
{
"type": "text",
"value": " "
}
]
}
]
},
{
"type": "listItem",
"loose": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/products",
"children": [
{
"type": "text",
"value": "Products"
}
]
}
]
}
]
},
{
"type": "listItem",
"loose": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/products/:id",
"children": [
{
"type": "text",
"value": "Product Details"
}
]
}
]
}
]
}
],
"position": {
"start": {
"line": 10,
"column": 1,
"offset": 240
},
"end": {
"line": 14,
"column": 35,
"offset": 358
}
}
}
]
}You can use all of this information to run scripts which run on behalf of, or in the context of, this document.
We can hook these scripts up to React Components. Combined with MDX, this turns markdown into living documents with user interfaces.