Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update docs to latest markdown #107

Merged
merged 8 commits into from
Dec 23, 2020
Merged

docs: update docs to latest markdown #107

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0156059
docs: update image doc
rafegoldberg Dec 23, 2020
d01c21f
docs: update list markdown
rafegoldberg Dec 23, 2020
3349988
docs: update tables markdown
rafegoldberg Dec 23, 2020
831d61e
docs: update embeds markdown
rafegoldberg Dec 23, 2020
4f4a7a7
docs: update callouts markdown
rafegoldberg Dec 23, 2020
d3e48e2
docs: update custom css markdown
rafegoldberg Dec 23, 2020
13de6fa
docs: update getting started markdown
rafegoldberg Dec 23, 2020
17cd493
docs: lol
rafegoldberg Dec 23, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 49 additions & 49 deletions docs/callouts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,15 @@ metadata:
3: 173
4: "#edf3ec"
---

[block:api-header]
{
"title": "Syntax"
}
[/block]
Callouts are very nearly equivalent to standard Markdown block quotes in their syntax, other than some specific requirements on their content: To be considered a “callout”, a block quote must start with an initial emoji. This is used to determine the callout's theme. Here's an example of how you might write a warning callout.

> 👍 [Success](#edge-cases)
> 👍 Success
>
> Vitae reprehenderit at aliquid error voluptates eum dignissimos.

Expand All @@ -33,6 +34,19 @@ Default themes are specified using one of the following emojis. (If you don't li
| 👍 | `.callout_okay` | ✅ |
| 🚧 | `.callout_warn` | ⚠️ |
| ❗️ | `.callout_error` | 🛑 |

<hr>
<details><summary><em>Tips & Tricks </em></summary><br>

If you have a block quote that starts with an initial emoji which *should not* be rendered as a ReadMe callout, just bold the emoji. It's a bit of a hack for sure, but it's easy enough, and hey: it works! So this:

> **👋** Lorem ipsum dolor sit amet consectetur adipisicing elit.

Renders to a plain ol' block quote:

> **👋** Lorem ipsum dolor sit amet consectetur adipisicing elit.

</details><hr>
[block:api-header]
{
"title": "Examples"
Expand Down Expand Up @@ -62,22 +76,6 @@ If a callout starts with an emoji that's not dedicated to one of the themes (abo
> 🥇 Themeless
>
> Lorem ipsum dolor sit amet consectetur adipisicing elit.

<!--
> ✅ Default themes using the alternate emoji!
-->

<details><summary><em>Tips & Tricks </em></summary><hr>

If you have a block quote that starts with an initial emoji which *should not* be rendered as a ReadMe callout, just bold the emoji. It's a bit of a hack for sure, but it's easy enough, and hey: it works! So this:

> **👋** Lorem ipsum dolor sit amet consectetur adipisicing elit.

Renders to a plain ol' block quote:

> **👋** Lorem ipsum dolor sit amet consectetur adipisicing elit.

</details><hr>
[block:api-header]
{
"title": "Custom CSS"
Expand Down Expand Up @@ -106,21 +104,21 @@ Callouts come in [various themes](#section--examples-). These can be customized

Each callout will also have a `theme` attribute that's set to it's emoji prefix. Combined with a basic attribute selector, we should be able to create entirely new styles per-emoji, in addition to the built in themes above!

```markdown Markdown Syntax
> 🎅 Old Saint Nick
>
> 'Twas the night before Christmas, when all through the house not a creature was stirring, not even a mouse. The stockings were hung by the chimney with care, in hopes that St. Nicholas soon would be there. The children were nestled all snug in their beds, while visions of sugar plums danced in their heads.
```
```css Custom CSS
.markdown-body .callout[theme="🎅"] {
--background: #c54245;
--border: #ffffff6b;
--text: #f5fffa;
}
```
```markdown Markdown Syntax
> 🎅 Old Saint Nick
>
> 'Twas the night before Christmas, when all through the house not a creature was stirring, not even a mouse. The stockings were hung by the chimney with care, in hopes that St. Nicholas soon would be there. The children were nestled all snug in their beds, while visions of sugar plums danced in their heads.
```
```html Generated HTML
<!-- condensed for clarity! -->
<blockquote class="callout callout_default" theme="🎅">
<!-- essentially -->
<h3>🎅 Old Saint Nick</h3>
<p>'Twas the night before Christmas, when all through the house not a creature was stirring, not even a mouse. The stockings were hung by the chimney with care, in hopes that St. Nicholas soon would be there. The children were nestled all snug in their beds, while visions of sugar plums danced in their heads.</p>
</blockquote>
Expand All @@ -134,61 +132,63 @@ And voilà...

### Custom Icons

What if we wanted to use a custom icon instead of the emoji? With just a touch of Custom CSS, we should be able to display the callout's 📷 emoji using the icon glyph we found on FontAwesome's site!
[block:code]
{
"codes": [
{
"code": ".callout[theme=📷] {\n --emoji: unset;\n --icon: \"\\f083\";\n --icon-color: #c50a50;\n}",
"language": "css",
"name": "Custom Icons CSS"
}
]
}
[/block]
<details><summary>This works like a charm! (Click to compare the custom icon against the default.)</summary><br>
Emojis are already a pretty good starting point as far as default icon options go! There are a *lot* of 'em, and they're supported across nearly all platforms. But what if we're going for a different look, or need to match our docs to a branding kit? Icons are a big part of setting the "tone" for your site.

Here's what it looks like by default:
With a touch of Custom CSS, we should be able to get a callout using the 📷 emoji to display an icon font glyph!

```css Custom CSS
.callout[theme=📷] {
--emoji: unset;
--icon: "\f083"; /* copied front FontAwesome */
--icon-color: #c50a50;
}
```
``` Markdown Syntax
> 📷 Cool pix!
>
> Vitae reprehenderit at aliquid error voluptates eum dignissimos.
```

This works like a charm:

And here it is with our custom CSS:
</details>
<div id="my-theme">

> 📸 Cool pix!
> Vitae reprehenderit at aliquid error voluptates eum dignissimos.
[block:html]
{
"html": "<style>\n #my-theme .callout[theme=📸] {\n --emoji: unset;\n --icon: \"\";\n }\n #my-theme .callout[theme=📷],\n #my-theme .callout[theme=📸] {\n --icon-color: #c50a50;\n --border: var(--icon-color);\n --title: var(--icon-color);\n }\n summary {\n outline: none;\n user-select: none;\n }\n</style>"
}
[/block]
</div>

<hr><details><summary><em>Setting the Custom Icon Font</em></summary><br>

The custom icon font defaults to `FontAwesome`, but you can use any font family available on the page by setting the `--icon-font` variable!

```css
.callout[theme=📷] {
/* etc. */
--icon-font-family:
--icon-font-family: FontAwesome; /* copied from https://fontawesome.com/v4.7.0/icon/camera-retro */
}
```
[block:html]
{
"html": "<style>\n .callout[theme=📸] {\n --emoji: unset;\n --icon: \"\";\n }\n .callout[theme=📷],\n .callout[theme=📸] {\n --icon-color: #c50a50;\n --border: var(--icon-color);\n --title: var(--icon-color);\n }\n details, summary {\n outline: none;\n }\n</style>"
}
[/block]

</details><hr>
[block:api-header]
{
"title": "Edge Cases"
}
[/block]
Callouts don't need to have any body text:

> 🥈 No body text.
> 🥇 No body text.

You can also skip the title, if you're so inclined!

> 🥉
> 🥈
>
> Lorem ipsum dolor sit amet consectetur adipisicing elit. Error eos animi obcaecati quod repudiandae aliquid nemo veritatis ex, quos delectus minus sit omnis vel dolores libero, recusandae ea dignissimos iure?
[block:html]
{
"html": "<style>\n.markdown-body .callout[theme=\"🎅\"] {\n --background: #c50a4f;\n --border: #ffffff6b;\n --text: #f5fffa;\n}\n</style>"
}
[/block]
[/block]
17 changes: 1 addition & 16 deletions docs/custom-css.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,21 +35,6 @@ The new Markdown engine uses CSS variables to enable simple theming for all mode
--markdown-font: Papyrus, serif;
--markdown-text: #333;
--markdown-title: hotpink;
--markdown-lineHeight: 2;
--markdown-line-height: 2;
}
```

## Styling Components

### Callouts

Our callouts have been refactored to be based on the default block quote element and styling. It comes with various themes, which can be customized using the following selectors. [**More**](doc:callouts)...

### Tables

Tables have been simplified to mirror a more standard implementation, which should make them easier to style. [**More**](doc:tables)...
[block:html]
{
"html": "<style>\n.callout.callout_default[theme=🐷] {\n --background: #fdf2fa;\n --title: #ed32ba;\n --border: var(--title);\n}\n</style>"
}
[/block]
47 changes: 43 additions & 4 deletions docs/embeds.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: "Embeds"
slug: "embeds"
hidden: false
---

[block:api-header]
{
"title": "Syntax"
Expand All @@ -16,7 +17,27 @@ Embedded content is written as a simple Markdown link, with a title of "@embed",
"title": "Examples"
}
[/block]
### Magic Block

[block:embed]
{
"html": false,
"url": "https://github.com/readmeio/api-explorer/pull/671",
"title": "RDMD CSS theming and style adjustments. by rafegoldberg · Pull Request #671 · readmeio/api-explorer",
"favicon": "https://github.com/favicon.ico",
"image": "https://avatars2.githubusercontent.com/u/6878153?s=400&v=4"
}
[/block]

[block:embed]
{
"html": false,
"url": "https://www.nytimes.com/2020/05/03/us/politics/george-w-bush-coronavirus-unity.html",
"title": "George W. Bush Calls for End to Pandemic Partisanship",
"favicon": "https://www.nytimes.com/vi-assets/static-assets/favicon-4bf96cb6a1093748bf5b3c429accb9b4.ico",
"image": "https://static01.nyt.com/images/2020/05/02/world/02dc-virus-bush-2/merlin_171999921_e857a690-fb9b-462d-a20c-28c8161107c9-facebookJumbo.jpg"
}
[/block]
<details><summary><b>Magic Block</b> (Embedly)</summary><br>
[block:embed]
{
"html": "<iframe class=\"embedly-embed\" src=\"//cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FJ3-uKv1DShQ%3Ffeature%3Doembed&display_name=YouTube&url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DJ3-uKv1DShQ&image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FJ3-uKv1DShQ%2Fhqdefault.jpg&key=f2aa6fc3595946d0afc3d76cbbd25dc3&type=text%2Fhtml&schema=youtube\" width=\"640\" height=\"480\" scrolling=\"no\" title=\"YouTube embed\" frameborder=\"0\" allow=\"autoplay; fullscreen\" allowfullscreen=\"true\"></iframe>",
Expand All @@ -26,10 +47,28 @@ Embedded content is written as a simple Markdown link, with a title of "@embed",
"image": "https://i.ytimg.com/vi/J3-uKv1DShQ/hqdefault.jpg"
}
[/block]
### Markdown Block
</details>
<details><summary><b>Magic Block</b> (iFrame)</summary><br>
[block:embed]
{
"html": "<iframe class=\"embedly-embed\" src=\"//cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.google.com%2Fmaps%2Fembed%2Fv1%2Fplace%3Fcenter%3D37.829698%252C-122.258166%26key%3DAIzaSyD9HrlRuI1Ani0-MTZ7pvzxwxi4pgW0BCY%26zoom%3D16%26q%3DMama%27s%2BRoyal%2BCafe&display_name=Google+Maps&url=https%3A%2F%2Fwww.google.com%2Fmaps%2Fplace%2FMama%27s%2BRoyal%2BCafe%2F%4037.829698%2C-122.258166%2C16z%2Fdata%3D%214m13%211m7%213m6%211s0x80857dfb145a04ff%3A0x96b17d967421636f%212s4126%2BOpal%2BSt%2C%2BOakland%2C%2BCA%2B94609%213b1%218m2%213d37.8296978%214d-122.2581661%213m4%211s0x0%3A0x722326b6c2ac7642%218m2%213d37.8277961%214d-122.2563006%3Fhl%3Den&image=http%3A%2F%2Fmaps-api-ssl.google.com%2Fmaps%2Fapi%2Fstaticmap%3Fcenter%3D37.829698%2C-122.258166%26zoom%3D15%26size%3D250x250%26sensor%3Dfalse&key=f2aa6fc3595946d0afc3d76cbbd25dc3&type=text%2Fhtml&schema=google\" width=\"600\" height=\"450\" scrolling=\"no\" title=\"Google Maps embed\" frameborder=\"0\" allow=\"autoplay; fullscreen\" allowfullscreen=\"true\"></iframe>",
"url": "https://www.google.com/maps/place/Mama's+Royal+Cafe/@37.829698,-122.258166,16z/data=!4m13!1m7!3m6!1s0x80857dfb145a04ff:0x96b17d967421636f!2s4126+Opal+St,+Oakland,+CA+94609!3b1!8m2!3d37.8296978!4d-122.2581661!3m4!1s0x0:0x722326b6c2ac7642!8m2!3d37.8277961!4d-122.2563006?hl=en",
"title": "Mama's Royal Cafe",
"favicon": "https://www.google.com/images/branding/product/ico/maps15_bnuw3a_32dp.ico",
"image": "http://maps-api-ssl.google.com/maps/api/staticmap?center=37.829698,-122.258166&zoom=15&size=250x250&sensor=false"
}
[/block]
</details>
<details><summary><b>Markdown Block</b></summary><br>

[Embed Title](https://youtu.be/8bh238ekw3 "@embed")

## Known Issues
</details>

At the moment, embed links written in the new ReadMe-flavored markdown syntax will simply display the link. (Magic block embeds will continue to work, though!) We're aware of the shortcoming, and plan to refactor this component as we move forward.
## Known Issues
At the moment, embed links written in the new ReadMe-flavored markdown syntax will simply display the link. (Magic block embeds will continue to work, though!) We're aware of the shortcoming, and plan to refactor this component as we move forward.
[block:html]
{
"html": "<style>\n summary {\n outline: none;\n user-select: none;\n }\n</style>"
}
[/block]
16 changes: 8 additions & 8 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,10 @@ metadata:
3: 315
4: "#2caaf8"
---
[<img src=https://github.com/readmeio/api-explorer/workflows/CI/badge.svg align=right />](https://www.npmjs.com/package/@readme/markdown) A remark-based Markdown engine for parsing and rendering ReadMe docs. (In fact, you're looking at it right now, since we've used it to render every doc in this project!)
[<img src=https://github.com/readmeio/markdown/workflows/CI/badge.svg align=right style="margin-top: 3px; margin-bottom: 3px;" />](https://www.npmjs.com/package/@readme/markdown) A remark-based Markdown engine for parsing and rendering ReadMe docs. (In fact, you're looking at it right now, since we've used it to render every doc in this project!)

```bash
npm i -S @readme/markdown
npm install --save @readme/markdown
```

> 🧙‍ **Backwards Compatible**
Expand Down Expand Up @@ -52,24 +52,24 @@ This gives you various methods and utilities:

| Export | Description | Arguments |
|:------------- |:---------------------------------------------- | ----------------:|
| *`react`* |_default;_ returns a VDOM React tree | `text`, `options`|
| *`react`* |_default;_ returns a VDOM React tree | `text`, `options`|
| *`html`* | transform markdown in to HTML | `text`, `options`|
| *`ast`* | transform markdown to an mdast object | `text`, `options`|
| *`md`* | transform mdast in to ReadMe-flavored markdown | `ast`, `options`|
| *`md`* | transform mdast in to ReadMe-flavored markdown | `ast`, `options` |

### Utilities

The `rdmd.utils` export gives you access to various tools and configuration settings:
The `utils` export gives you access to various tools and configuration settings:

- **`options`**
_a hash of default settings accepted by the rdmd engine._
- `markdownOptions`—configuration object passed to `remark`
- `correctnewlines`—flag to toggle newline transformation.
- `normalize`—auto-normalize magic blocks before processing.
- **`<GlossaryContext/>`** and **`<VariablesContext/>`**
React provider and consumer wrappers for [ReadMe data replacement.](doc:features#section-data-replacement).
React provider and consumer wrappers for [user data injection](doc:features#section-data-injection).
[block:html]
{
"html": "<style>\n .markdown-body .callout.callout_default[theme=🧙‍]{\n --background: #fffae7;\n --border: #e6b8086e;\n --title: #e0b400;\n }\n</style>"
"html": "<style>\n .markdown-body .callout.callout_default[theme=🧙‍]{\n --background: #fffae7;\n --border: #e6b8086e;\n --title: #e0b400;\n }\n</style>"
}
[/block]
[/block]
28 changes: 19 additions & 9 deletions docs/images.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,29 @@ title: "Images"
slug: "images"
hidden: false
---
[block:callout]
{
"type": "warning",
"title": "Known Issue",
"body": "The ReadMe-flavored markdown engine does not currently support lightbox functionality (click-to-zoom). **[But we're working on it!](https://github.com/readmeio/api-explorer/issues/621)**"
}
[/block]
## Syntax

![Alt text](https://cdn.path.to/some/image.jpg "Image Title")
![Alt text](https://cdn.path.to/some/image.jpg "This is some image...")
[block:api-header]
{
"title": "Examples"
}
[/block]
![Bro eats pizza and makes an OK gesture.](https://files.readme.io/6f52e22-man-eating-pizza-and-making-an-ok-gesture.jpg "Pizza Face")

[block:image]
{
"images": [
{
"image": [
"https://files.readme.io/b8674d6-pizzabro.jpg",
"pizzabro.jpg",
1024,
682,
"#d1c8c5"
],
"caption": "Click to zoom."
}
]
}
[/block]
<!-- ![Bro eats pizza and makes an OK gesture.](https://files.readme.io/6f52e22-man-eating-pizza-and-making-an-ok-gesture.jpg "Pizza Face") -->
Loading