This works like a charm! (Click to compare the custom icon against the default.)
-With a touch of Custom CSS, we should be able to get a callout using the 📷 emoji to display an icon font glyph! +Here's what it looks like by default: -```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:
+
> 📸 Cool pix!
> Vitae reprehenderit at aliquid error voluptates eum dignissimos.
-[block:html]
-{
- "html": ""
-}
-[/block]
-
-
-Setting the Custom Icon Font
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=📷] { - --icon-font-family: FontAwesome; /* copied from https://fontawesome.com/v4.7.0/icon/camera-retro */ + /* etc. */ + --icon-font-family: } ``` +[block:html] +{ + "html": "" +} +[/block] -
[block:api-header] { "title": "Edge Cases" @@ -165,15 +180,15 @@ The custom icon font defaults to `FontAwesome`, but you can use any font family [/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": "" } -[/block] +[/block] \ No newline at end of file diff --git a/example/Fixtures/Syntax/code-blocks/code-block-tests.md b/docs/code-block-tests.md similarity index 94% rename from example/Fixtures/Syntax/code-blocks/code-block-tests.md rename to docs/code-block-tests.md index 6e603cb7d..69e4bc999 100644 --- a/example/Fixtures/Syntax/code-blocks/code-block-tests.md +++ b/docs/code-block-tests.md @@ -1,5 +1,11 @@ +--- +title: "Code Block Tests" +slug: "code-block-tests" +hidden: true +--- Basics === + ### Simple ```php ; diff --git a/example/Fixtures/Syntax/code-blocks.md b/docs/code-blocks.md similarity index 96% rename from example/Fixtures/Syntax/code-blocks.md rename to docs/code-blocks.md index de43af1ea..d7e5e6b78 100644 --- a/example/Fixtures/Syntax/code-blocks.md +++ b/docs/code-blocks.md @@ -1,3 +1,9 @@ +--- +title: "Code Blocks" +slug: "code-blocks" +hidden: false +--- + [block:api-header] { "title": "Examples" @@ -106,4 +112,4 @@ We support syntax highlighting on a number of languages: | SQL | `cql`, `mssql`, `mysql`, `plsql`, `postgres`, `postgresql`, `pgsql`, `sql`, `sqlite` | | Swift | `swift` | | TypeScript | `ts`, `typescript` | -| YAML | `yaml`, `yml` | +| YAML | `yaml`, `yml` | \ No newline at end of file diff --git a/docs/custom-css.md b/docs/custom-css.md new file mode 100644 index 000000000..14ce3de1f --- /dev/null +++ b/docs/custom-css.md @@ -0,0 +1,55 @@ +--- +title: "Custom Styling" +slug: "custom-css" +excerpt: "Styling best-practices and CSS selector references." +hidden: false +--- +By and large, the new markdown processor outputs standard HTML. This means most basic CSS element selectors will continue to work seamlessly. Depending on how complex your Markdown and custom CSS are, you should only have to update a few styles here and there! + +> 🐷 **Need CSS Help?** +> +> We're always happy to help troubleshoot tricky styling issues! [Shoot us an email](mailto:support@readme.io?subject=ReadMe-Flavored+Markdown+Feedback), and we'll try to make ourselves useful. + +## Scoping Your Styles + +When writing custom styles for the new processor, you should explicitly target content generated by the new Markdown engine using the **`.markdown-body`** class prefix. You can also style Markdown for a specific template by adding additional prefixes. + +```scss Markdown Selector Scope +/* Guides Pages */ +#content-body .markdown-body {} + +/* Reference Pages */ +#api-explorer .markdown-body {} +#api-explorer .markdown-body > .pin {} /* target pinned sidebar content */ +``` + +> **Note**: The `.markdown-body` prefix is unique to the new engine, which is useful when refactoring custom styles. In the run up to the production release, this can be a useful “hook” for progressively enhancing your custom CSS. Just prefix your selectors with the `.markdown-body` class and appending the new ruleset to your custom CSS + +## CSS Variables Theming + +The new Markdown engine uses CSS variables to enable simple theming for all modern browsers (i.e. IE11+.) Certain custom components offer their own theme variables. The markdown engine also offers some high-level theming variables: + +```css +.markdown-body { + --markdown-radius: 3px; + --markdown-font: Papyrus, serif; + --markdown-text: #333; + --markdown-title: hotpink; + --markdown-lineHeight: 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": "" +} +[/block] \ No newline at end of file diff --git a/docs/embeds.md b/docs/embeds.md new file mode 100644 index 000000000..9b1bdbbce --- /dev/null +++ b/docs/embeds.md @@ -0,0 +1,35 @@ +--- +title: "Embeds" +slug: "embeds" +hidden: false +--- +[block:api-header] +{ + "title": "Syntax" +} +[/block] +Embedded content is written as a simple Markdown link, with a title of "@embed", like so: + + [Embed Title](https://youtu.be/8bh238ekw3 "@embed") +[block:api-header] +{ + "title": "Examples" +} +[/block] +### Magic Block +[block:embed] +{ + "html": "", + "url": "https://www.youtube.com/watch?v=J3-uKv1DShQ&feature=youtu.be", + "title": "Funny Solidier Drop Kick", + "favicon": "https://s.ytimg.com/yts/img/favicon-vfl8qSV2F.ico", + "image": "https://i.ytimg.com/vi/J3-uKv1DShQ/hqdefault.jpg" +} +[/block] +### Markdown Block + +[Embed Title](https://youtu.be/8bh238ekw3 "@embed") + +## 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. \ No newline at end of file diff --git a/example/Fixtures/Syntax/features.md b/docs/features.md similarity index 75% rename from example/Fixtures/Syntax/features.md rename to docs/features.md index b6d17e471..f040a24f4 100644 --- a/example/Fixtures/Syntax/features.md +++ b/docs/features.md @@ -1,11 +1,12 @@ +--- +title: "And more..." +slug: "features" +excerpt: "Additional Markdown features of the ReadMe platform implementation." +hidden: false +--- We've also built a lot of great features right in to the ReadMe app, which work on top of our markdown engine to give your developers a best-in-class documentation experience. These features aren't all baked in to the new engine itself, but they're worth mentioning nonetheless! -## Sectioning Semantics - -- Automatic **table of contents** based on sections. -- Generated **[heading anchor links](doc:headings#section-incremented-anchors)**. - -## Data Injection +## Data Replacement #### User Variables @@ -30,3 +31,12 @@ You can use GitHub-style emoji short codes (feat. Owlbert!) :sparkles: :owlbert-reading: This expands out to: “:sparkles: :owlbert-reading:” + +## Generative Semantics + +- Markup-based TOC generation. +- Auto-generated [heading anchors](doc:headings#section-incremented-anchors). + +## Known Issues + +- Variable and glossary term expansions are rendered even when they've been manually escaped by the author. \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 000000000..02d96dabf --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,75 @@ +--- +title: "Getting Started" +slug: "getting-started" +excerpt: "ReadMe's Markdown engine, with notes of GitHub, modern styles, and a hint of magic." +hidden: false +metadata: + title: "ReadMe-Flavored Markdown" + description: "ReadMe's Markdown engine, with notes of GitHub, modern styles, and a hint of magic." + image: + 0: "https://files.readme.io/aafdc0b-share-image" + 1: "share-image" + 2: 600 + 3: 315 + 4: "#2caaf8" +--- +[
](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
+```
+
+> 🧙 **Backwards Compatible**
+>
+> Our old engine was based on a format we call "magic blocks". This was our custom, JSON-based syntax for writing rich components alongside plain-text Markdown. To provide seamless backwards-compatibility, the engine ships with a built-in parser for the older format so we can transpile it directly to our new ReadMe-flavored syntax.
+
+## Usage
+
+By default, the Markdown library exports a function which takes a string of [ReadMe-flavored markdown](#readme-flavored-syntax) and returns a tree of React components:
+
+```javascript Component
+import React from 'react';
+import rdmd from '@readme/markdown';
+
+export default ({ body }) => (
+
+ {rdmd(body)}
+
+);
+```
+
+## Exports
+
+### Transformers
+
+In addition to the default React processor, the package exports a few other methods for parsing and rendering ReadMe-flavored markdown:
+
+```javascript
+import * as rdmd from '@readme/markdown';
+```
+
+This gives you various methods and utilities:
+
+| Export | Description | Arguments |
+|:------------- |:---------------------------------------------- | ----------------:|
+| *`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`|
+
+### Utilities
+
+The `rdmd.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.
+- **`
-
+### Unordered Lists + +#### Bulleted List - Item Zed - * Nested Item - * Nested Item + * Nested Bullet + * Nested Bullet - Item One - Item Two -
-Bulleted List
+### Unordered Lists + +#### Bulleted List - Item Zed - * Nested Item - * Nested Item + * Nested Bullet + * Nested Bullet - Item One - Item Two -
-
+### Ordered List 1. Item Zed 1. Nested Numeric @@ -41,16 +26,12 @@ 1. Item One 2. Item Two -
-Ordered List
+### Ordered List 1. Item Zed 1. Nested Numeric @@ -41,16 +26,12 @@ 1. Item One 2. Item Two -
-
+#### Check List - [ ] Task Zed - [x] Task One - [ ] Task Two -
-
## Edge Cases
### Split Lists
@@ -81,9 +62,4 @@ Starting an ordered list with any number will increment continuously from that p
98. Starting in media res
98. Another list item
-98. Yet another item
-[block:html]
-{
- "html": ""
-}
-[/block]
+98. Yet another item
\ No newline at end of file
diff --git a/docs/syntax-extensions.md b/docs/syntax-extensions.md
new file mode 100644
index 000000000..c383aeef3
--- /dev/null
+++ b/docs/syntax-extensions.md
@@ -0,0 +1,31 @@
+---
+title: "Flavored Syntax"
+slug: "syntax-extensions"
+excerpt: "Specs and examples of ReadMe's (restrained) Markdown syntax extensions."
+hidden: false
+---
+Custom Blocks
+---
+
+### Code Tabs
+
+A tabbed interface for displaying multiple code blocks. These are written nearly identically to a series of vanilla markdown code snippets, except for their distinct *lack* of an additional line break separating each subsequent block. [**Syntax & examples**.](doc:code-blocks)
+
+### Callouts
+
+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”, the block quote must start with an initial emoji, which is used to determine the callout's theme. [**Syntax & examples**.](doc:callouts)
+
+### Embeds
+
+Embedded content is written as a simple Markdown link, with a title of "@embed". [**Syntax & examples**.](doc:embeds)
+
+Standard Markdown
+---
+
+The engine also supports all standard markdown constructs, as well as CommonMark options, and most GitHub syntax extensions.
+
+- [**Tables**](doc:tables)
+- [**Lists**](doc:lists)
+- [**Headings**](doc:headings)
+- [**Images**](doc:images)
+- **Decorations** (link, strong, and emphasis tags, etc.)
\ No newline at end of file
diff --git a/example/Fixtures/Syntax/tables.md b/docs/tables.md
similarity index 68%
rename from example/Fixtures/Syntax/tables.md
rename to docs/tables.md
index df9f21f4e..0bad58a74 100644
--- a/example/Fixtures/Syntax/tables.md
+++ b/docs/tables.md
@@ -1,14 +1,18 @@
+---
+title: "Tables"
+slug: "tables"
+hidden: false
+---
## Syntax
+> **Note**: table cells may contain inline decorations only.
+
| Left | Center | Right |
|:-----|:--------:|------:|
| L0 | **bold** | $1600 |
| L1 | `code` | $12 |
| L2 | _italic_ | $1 |
-> ❗️ Table cells may contain inline decorations only.
-> Lists, headings, and other block-level Markdown components are not valid and will cause errors.
-
### Examples
This example also shows off custom theming!
@@ -26,11 +30,11 @@ Tables have been simplified to mirror a more standard implementation. We've also
```scss CSS Variables
.markdown-body .rdmd-table {
--table-text: black;
- --table-head: #5b1c9f;
+ --table-head: #f44336;
--table-head-text: white;
- --table-stripe: #f0eaf7;
- --table-edges: rgba(34, 5, 64, .5);
- --table-row: white;
+ --table-stripe: #FFCDD2;
+ --table-edges: rgba(183, 28, 28, .33);
+ --table-row: #FFEBEE;
}
```
```scss CSS Selectors
@@ -51,6 +55,6 @@ Tables have been simplified to mirror a more standard implementation. We've also
```
[block:html]
{
- "html": ""
+ "html": ""
}
-[/block]
+[/block]
\ No newline at end of file
diff --git a/example/Fixtures/Syntax/code-blocks/vars-test.md b/docs/variable-tests.md
similarity index 56%
rename from example/Fixtures/Syntax/code-blocks/vars-test.md
rename to docs/variable-tests.md
index b203293d5..6b9f207d7 100644
--- a/example/Fixtures/Syntax/code-blocks/vars-test.md
+++ b/docs/variable-tests.md
@@ -1,3 +1,8 @@
+---
+title: "Variable Tests"
+slug: "variable-tests"
+hidden: true
+---
<Check List
+#### Check List - [ ] Task Zed - [x] Task One - [ ] Task Two -
Magic Block (Embedly)
-[block:embed] -{ - "html": "", - "url": "https://www.youtube.com/watch?v=J3-uKv1DShQ&feature=youtu.be", - "title": "Funny Solidier Drop Kick", - "favicon": "https://s.ytimg.com/yts/img/favicon-vfl8qSV2F.ico", - "image": "https://i.ytimg.com/vi/J3-uKv1DShQ/hqdefault.jpg" -} -[/block] -
Magic Block (iFrame)
-[block:embed] -{ - "html": "", - "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] -
Markdown Block
- -[Embed Title](https://youtu.be/8bh238ekw3 "@embed") - -