Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Speaker Deck
PRO
Sign in
Sign up
for free
Markdown, my friend – we have to talk
stefan judis
September 11, 2018
Technology
2
360
Markdown, my friend – we have to talk
stefan judis
September 11, 2018
Tweet
Share
More Decks by stefan judis
See All by stefan judis
stefanjudis
3
1.3k
stefanjudis
0
670
stefanjudis
0
310
stefanjudis
1
210
stefanjudis
5
3.3k
stefanjudis
1
140
stefanjudis
1
310
stefanjudis
0
560
stefanjudis
0
71
Other Decks in Technology
See All in Technology
ocise
0
130
asaju7142501
0
270
clustervr
0
190
yokatsuki
1
190
sylph01
0
170
ocise
1
1.3k
vkbaba
0
130
smzksts
0
220
neo_analytics
1
1k
kyonmm
1
2k
ray_30cm_ns
0
280
hacker2202
0
760
Featured
See All Featured
brianwarren
83
4.7k
jnunemaker
PRO
40
4.5k
samlambert
237
9.9k
mongodb
23
3.8k
hatefulcrawdad
257
17k
notwaldorf
13
1.5k
pedronauck
652
110k
tammielis
237
23k
lauravandoore
11
1.2k
hursman
106
9.2k
holman
461
280k
smashingmag
229
18k
Transcript
@stefanjudis *Markdown, my friend* **We have to talk!**
STEFAN JUDIS @stefanjudis www.stefanjudis.com stefan.judis@contentful.com
None
What have these sites in common?
WYSIWYG
“ I don't want to and feel bad setting up
polluted WYSIWYG editors.
None
Everything is broken!
None
None
It's a mix of content and presentation
Html
Html
Too flexible Too easy to mess up Mixes content and
looks HTML is the goal
You want to limit the user!
Markdown
# Heading ## Sub-heading Text attributes _italic_, **bold**, `monospace`. Bullet
list: * apples * oranges * pears A [link](http://example.com).  Heading Sub-heading Text attributes italic, bold, monospace. Bullet list: - apple - oranges - pears A link.
Inline <abbr title="Hypertext Markup Language">HTML</abbr> is supported. Inline HTML is
supported.
“ The key design goal [of markdown] is readability.
None
None
Markdown is not "feature-complete" ("semantical correct" is not a thing)
# Heading And a paragraph...
# Heading And a paragraph... 
None
Responsive images
// my-markdown-renderer.js import marked from 'marked' export default (text) =>
marked(text);
// my-markdown-renderer.js import marked from 'marked' const renderer = new
marked.Renderer() export default (text) => marked(text, { renderer });
// my-markdown-renderer.js import marked from 'marked' const renderer = new
marked.Renderer() renderer.image = (href, title, text) => { return `<img src="${href}" srcset="https: //images.contentful.com/ .../duck.png?w=100 100w, https: //images.contentful.com/ .../duck.png?w=500 500w, https: //images.contentful.com/ .../duck.png?w1000 1000w" sizes="(min-width: 900px) 1000px, (max-width: 900px) and (min-width: 400px) 50em" alt="${text}">` } export default (text) => marked(text, { renderer });
// my-markdown-renderer.js import marked from 'marked' const renderer = new
marked.Renderer() renderer.image = (href, title, text) => { return `<img src="${href}" srcset="https: //images.contentful.com/ .../duck.png?w=100 100w, https: //images.contentful.com/ .../duck.png?w=500 500w, https: //images.contentful.com/ .../duck.png?w1000 1000w" sizes="(min-width: 900px) 1000px, (max-width: 900px) and (min-width: 400px) 50em" alt="${text}">` } export default (text) => marked(text, { renderer });
# Heading And a paragraph... 
# Heading And a paragraph...  And a paragraph... 
And a paragraph...
# Heading And a paragraph... ??? And a paragraph... 
And a paragraph...
"Video hack"
// my-markdown-renderer.js import marked from 'marked' const renderer = new
marked.Renderer() renderer.image = (href, title, text) => { return `<img src="${href}" srcset="https: //images.contentful.com/ .../duck.png?w=100 100w, https: //images.contentful.com/ .../duck.png?w=500 500w, https: //images.contentful.com/ .../duck.png?w1000 1000w" sizes="(min-width: 900px) 1000px, (max-width: 900px) and (min-width: 400px) 50em" alt="${text}">` } export default (text) => marked(text, { renderer });
// my-markdown-renderer.js import marked from 'marked' const renderer = new
marked.Renderer() renderer.image = (href, title, text) => { if (/\.mp4$/.test(href)) { return ` <video controls preload="metadata"> <source src="${href}" type="video/mp4"> </video> ` } return `<img src="${href}" srcset="https: //images.contentful.com/ .../duck.png?w=100 100w, https: //images.contentful.com/ .../duck.png?w=500 500w, https: //images.contentful.com/ .../duck.png?w1000 1000w" sizes="(min-width: 900px) 1000px, (max-width: 900px) and (min-width: 400px) 50em" alt="${text}">` } export default (text) => marked(text, { renderer });
// my-markdown-renderer.js import marked from 'marked' const renderer = new
marked.Renderer() renderer.image = (href, title, text) => { if (/\.mp4$/.test(href)) { return ` <video controls preload="metadata"> <source src="${href}" type="video/mp4"> </video> ` } return `<img src="${href}" srcset="https: //images.contentful.com/ .../duck.png?w=100 100w, https: //images.contentful.com/ .../duck.png?w=500 500w, https: //images.contentful.com/ .../duck.png?w1000 1000w" sizes="(min-width: 900px) 1000px, (max-width: 900px) and (min-width: 400px) 50em" alt="${text}">` } export default (text) => marked(text, { renderer });
// my-markdown-renderer.js import marked from 'marked' const renderer = new
marked.Renderer() renderer.image = (href, title, text) => { if (/\.mp4$/.test(href)) { return ` <video controls preload="metadata"> <source src="${href}" type="video/mp4"> </video> ` } return `<img src="${href}" srcset="https: //images.contentful.com/ .../duck.png?w=100 100w, https: //images.contentful.com/ .../duck.png?w=500 500w, https: //images.contentful.com/ .../duck.png?w1000 1000w" sizes="(min-width: 900px) 1000px, (max-width: 900px) and (min-width: 400px) 50em" alt="${text}">` } export default (text) => marked(text, { renderer }); Not pretty, but "works"
# Heading And a paragraph...  And a paragraph... 
And a paragraph...
# Heading And a paragraph...  And a paragraph... 
And a paragraph...
# Heading And a paragraph...  And a paragraph... ???
And a paragraph...
# Heading And a paragraph... ???  And a paragraph...
??? And a paragraph...
# Heading And a paragraph... ???  And a paragraph...
??? ??? !!! ??? Duck!
# Heading And a paragraph... ???  And a paragraph...
??? ??? !!! ??? Duck! Markdown is not made for "complex" use cases
Limited functionality Focuses on semantics Easy to grasp
Limited functionality Not powerful enough Editors don't like it HTML
is "allowed"
How can you solve this with Contentful?
www.contentful.com/r/knowledgebase/topics-and-assemblies/
None
Duck!
{ "sys": { "contentType": { "sys": { "id": "page" }
} }, "fields": { "title": "Page", "components": [ { "sys": { "contentType": { "sys": { "id": "chart" } } } } ] }, ... }
{ "sys": { "contentType": { "sys": { "id": "page" }
} }, "fields": { "title": "Page", "components": [ { "sys": { "contentType": { "sys": { "id": "chart" } } } } ] }, ... } <Page> <Chart /> ... </Page>
{ "sys": { "contentType": { "sys": { "id": "page" }
} }, "fields": { "title": "Page", "components": [ { "sys": { "contentType": { "sys": { "id": "chart" } } } } ] }, ... } <Page> <Chart /> ... </Page> Structured data is perfect for a component-driven approach!
www.contentful.com/blog/2017/10/11/love-letter-to-component-ready-cms/
www.youtube.com/watch?v=i17FKTtIifM&t=408s
MDX
“ MDX is Markdown + JSX, bringing the world of
components to Markdown.
import { Chart } from ' ../components/chart' # Here's a
chart The chart is rendered inside our MDX document. <Chart />
www.docz.site
revealjs.com
jxnblk.com/mdx-deck/
None
It's Reveal.js on steroids.
Are these slide made with mdx-deck?
Could this work in Contentful?
Demo
codesandbox.io
www.npmjs.com/package/smooshpack
None
Stefan, you're breaking portability!
Yeah, kinda...
None
Devs will love it Perfect for docs Component-based
Easy to mess up Not made for publishing Needs file
access Breaks portability easily
None
Love it! But it's not suited for our content editing
needs.
A [link](http://example.com).
A [link](http://example.com).
Duck!
Duck! Duck!
Duck! Duck! Duck!
Duck! Duck! Duck! Duck!
Alice! Alice! Alice! Alice!
Alice! Alice! Alice! Alice! That's not possible with hardcoded values.
Back to square one!
None
None
None
None
Structured Text
Demo
None
www.npmjs.com/package/@contentful/structured-text-html-serializer
www.npmjs.com/package/@contentful/structured-text-html-serializer Serializer will be available for common languages
It supports underline Visual interface Fewer content types
Incoming links support Connected editing flow Platform-portable
www.contentful.com/r/knowledgebase/topics-and-assemblies/
www.contentful.com/r/knowledgebase/topics-and-assemblies/ Topics & Assemblies will still be a thing
Proper content modelling stays important!
So, what about the hover-duck? Duck!
Inline references will be possible Duck!
You can sign up for the alpha today. Talk to
me!
THANKS FOR LISTENING @stefanjudis