markdown example improvements (#1360)

Author: mbostock

examples/markdown-it-container/README.md

@@ -1,6 +1,6 @@
 [Framework examples →](../)
 
-# Framework + markdown-it-container
+# markdown-it-container
 
 View live: <https://observablehq.observablehq.cloud/framework-example-markdown-it-container/>
 

examples/markdown-it-container/src/index.md

@@ -1,13 +1,50 @@
-# Framework + markdown-it-container
+# markdown-it-container
 
+This Framework example demonstrates how to use [`markdown-it-container`](https://github.com/markdown-it/markdown-it-container), which extends Markdown to allow `:::` syntax for styled containers.
+
+First, install `markdown-it-container` with your preferred package manager such as npm or Yarn. Then, register the plugin using the **markdownIt** config option in your `observablehq.config.js` file. Declare as many custom containers as you like; below, we register three (`card`, `tip`, and `warning` — each corresponding to classes that are built-in to Framework).
+
+```js run=false
+import MarkdownItContainer from "markdown-it-container";
+
+export default {
+  root: "src",
+  markdownIt: (md) =>
+    md
+      .use(MarkdownItContainer, "card") // ::: card
+      .use(MarkdownItContainer, "tip") // ::: tip
+      .use(MarkdownItContainer, "warning") // ::: warning
+};
+```
+
+Below are some examples.
+
+::: card
+That’s a _nice_ card, ain’t it?
+:::
+
+```md run=false
 ::: card
 That’s a _nice_ card, ain’t it?
 :::
+```
 
 ::: tip
 That’s a _nice_ **tip**, ain’t it?
 :::
 
+```md run=false
+::: tip
+That’s a _nice_ **tip**, ain’t it?
+:::
+```
+
+::: warning
+That’s a _nice_ **warning**, ain’t it?
+:::
+
+```md run=false
 ::: warning
 That’s a _nice_ **warning**, ain’t it?
 :::
+```

examples/markdown-it-footnote/README.md

@@ -1,6 +1,6 @@
 [Framework examples →](../)
 
-# Framework + markdown-it-footnote
+# markdown-it-footnote
 
 View live: <https://observablehq.observablehq.cloud/framework-example-markdown-it-footnote/>
 

examples/markdown-it-footnote/src/index.md

@@ -1,11 +1,46 @@
-# Framework + markdown-it-footnote
+# markdown-it-footnote
+
+This Framework example demonstrates how to use [`markdown-it-footnote`](https://github.com/markdown-it/markdown-it-footnote) to create footnotes in Markdown.
+
+First, install `markdown-it-footnote` with your preferred package manager such as npm or Yarn. Then, register the plugin using the **markdownIt** config option in your `observablehq.config.js` file.
+
+```js run=false
+import MarkdownItFootnote from "markdown-it-footnote";
+
+export default {
+  root: "src",
+  markdownIt: (md) => md.use(MarkdownItFootnote)
+};
+```
+
+Below is an example of referencing a footnote.
 
 Here is a footnote reference,[^1] and another.[^longnote]
 
+```md run=false
+Here is a footnote reference,[^1] and another.[^longnote]
+```
+
+And here is how you can define the footnotes.
+
 [^1]: Here is the footnote.
 [^longnote]: Here's one with multiple blocks.
 
     Subsequent paragraphs are indented to show that they
     belong to the previous footnote.
 
-For more, see <https://observablehq.com/framework/getting-started>.
+```md run=false
+[^1]: Here is the footnote.
+[^longnote]: Here's one with multiple blocks.
+
+    Subsequent paragraphs are indented to show that they
+    belong to the previous footnote.
+```
+
+Footnotes always appear at the bottom of the page, regardless of where they are defined. The remaining text is gibberish so that the page is taller, allowing you to try clicking on the footnote references to scroll down and then clicking on ther return link to scroll back up again.
+
+Aliquam porta accumsan eros, ut posuere lorem congue at. Cras lobortis metus sit amet ex ullamcorper lobortis. Donec vitae nulla dictum, cursus nunc auctor, facilisis tellus. Morbi iaculis ex sed nisi tristique, a auctor elit suscipit. Vestibulum varius, massa in laoreet facilisis, quam arcu dictum metus, sit amet ultricies erat metus non elit. Quisque fringilla gravida sapien non facilisis. Aliquam a ligula vitae tellus rutrum tincidunt. Integer mattis suscipit ex vel egestas. Aenean pharetra sit amet tellus ac tempus.
+
+Cras dapibus porta posuere. Aenean tempus nulla eget sem auctor, eget interdum urna sodales. Mauris ullamcorper nec ipsum in tempor. Pellentesque eleifend rutrum nunc eu aliquam. Aliquam quis tellus ligula. Mauris mattis quis nibh vel tincidunt. Aliquam aliquam scelerisque nisl, ac aliquam arcu accumsan et. Nunc tempor condimentum quam a ullamcorper. Aliquam imperdiet ac neque in maximus. Proin urna urna, feugiat sed placerat vitae, fringilla ac diam. Morbi ac ipsum nunc.
+
+Morbi placerat sodales ex, a eleifend quam interdum a. Nullam tellus sem, convallis a finibus a, placerat sed ante. Nullam sit amet dictum mauris. In sed mattis risus, et pulvinar eros. Pellentesque commodo urna ipsum, vitae euismod erat mollis a. Sed ornare, turpis in maximus dapibus, urna nibh dictum leo, suscipit mattis diam tellus ac ante. Vestibulum placerat, justo sit amet ultricies ultricies, orci massa aliquam purus, id ullamcorper odio urna nec leo.

examples/markdown-it-wikilinks/README.md

@@ -1,6 +1,6 @@
 [Framework examples →](../)
 
-# Hello, markdown-it-wikilinks
+# markdown-it-wikilinks
 
 View live: <https://observablehq.observablehq.cloud/framework-example-markdown-it-wikilinks/>
 

examples/markdown-it-wikilinks/observablehq.config.js

@@ -4,7 +4,7 @@ export default {
   root: "src",
 
   // Register the markdown-it-wikilinks plugin.
-  markdownIt: (md) => md.use(MarkdownItWikilinks({})),
+  markdownIt: (md) => md.use(MarkdownItWikilinks()),
 
   // Shared Observable example configuration; feel free to remove this.
   title: "Observable Framework",

examples/markdown-it-wikilinks/src/index.md

@@ -1,3 +1,22 @@
-# Hello, markdown-it-wikilinks
+# markdown-it-wikilinks
 
+This Framework example demonstrates how to use [`markdown-it-wikilinks`](https://github.com/jsepia/markdown-it-wikilinks) to create Wikimedia-style links in Markdown.
+
+First, install `markdown-it-wikilinks` with your preferred package manager such as npm or Yarn. Then, register the plugin using the **markdownIt** config option in your `observablehq.config.js` file.
+
+```js run=false
+import MarkdownItWikilinks from "markdown-it-wikilinks";
+
+export default {
+  root: "src",
+  markdownIt: (md) => md.use(MarkdownItWikilinks())
+};
+```
+
+Below is an example of a wikilink.
+
+Click [[Wiki Links|here]] to learn about [[/Wiki]] links.
+
+```md run=false
 Click [[Wiki Links|here]] to learn about [[/Wiki]] links.
+```