376 lines
21 KiB
Text
376 lines
21 KiB
Text
<div class="container article" id="editor-help-guide">
|
|
<div class="title help-guide-title">
|
|
<h1>Editor Guide 🤓</h1>
|
|
</div>
|
|
<div class="body">
|
|
<% if version == "1" %>
|
|
<%= render "pages/v1_editor_guide_preamble" %>
|
|
<% else %>
|
|
<p><em><b>We have two editor versions</b>. If you prefer Jekyll-style "frontmatter", switch to "basic markdown" in <a href="/settings/ux">/settings/ux</a>.</em></p>
|
|
<h2 style="font-size:2.8em"><strong>Things to Know</strong></h2>
|
|
<ul>
|
|
<li>Use <a href="#markdown"><strong>markdown</strong></a> to write and format <a href="/"><%= community_name %></a> posts.</li>
|
|
<li>Most of the time, you can write inline HTML directly into your posts.</li>
|
|
<li>You can use <strong><a href="#liquidtags">Liquid tags</a></strong> to make add rich content such as tweets and videos.</li>
|
|
<li>Links to unpublished posts are shareable for feedback/review.</li>
|
|
<li>The best size for your <b>cover image</b> is 1000 X 420.</li>
|
|
</ul>
|
|
<% end %>
|
|
<h2 style="font-size:2.8em" id="markdown"><strong>✍ Markdown Basics</strong></h2>
|
|
<p>Below are some examples of commonly used markdown syntax. If you want to dive deeper, check out
|
|
<a href="https://github.com/adam-p/markdown-here/wiki/Markdown-Here-Cheatsheet" target="_blank" rel="noopener">this cheat sheet.</a>
|
|
</p>
|
|
<h3><strong>Bold & Italic</strong></h3>
|
|
<p><em>Italics</em>: <code>*asterisks* or _underscores_</code></p>
|
|
<p><strong>Bold</strong>: <code>**double asterisks** or __double underscores__</code></p>
|
|
<h3><strong>Links</strong></h3>
|
|
<p><a href="<%= app_url %>">I'm an inline link</a>: <code>[I'm an inline link](put-link-here)</code></p>
|
|
<p><a name="anchored">Anchored links</a> (For things like a Table of Contents)</p>
|
|
<pre>
|
|
## Table Of Contents
|
|
* [Chapter 1](#chapter-1)
|
|
* [Chapter 2](#chapter-2)
|
|
|
|
### Chapter 1 <%= "<a name=\"chapter-1\"></a>" %>
|
|
</pre>
|
|
<h3><strong>Inline Images</strong></h3>
|
|
<p>
|
|
When adding GIFs to posts and comments, please note that there is a limit of 200 megapixels per frame/page.
|
|
<img src="https://res.cloudinary.com/practicaldev/image/fetch/s--OsLaFSo9--/c_fill,f_auto,fl_progressive,h_220,q_auto,w_220/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/31047/af153cd6-9994-4a68-83f4-8ddf3e13f0bf.jpg" alt="example image, with sloan" />
|
|
</p>
|
|
<pre></pre>
|
|
<figcaption> You can even add a caption using the HTML <code>figcaption</code> tag!</figcaption>
|
|
<h3><strong>Headers</strong></h3>
|
|
<p>Add a header to your post with this syntax:</p>
|
|
<pre># One '#' for a h1 header<br>## Two '#'s for a h2 header<br>...<br>###### Six '#'s for a h6 header</pre>
|
|
<h1>One '#' for a h1 header</h1>
|
|
<h2>Two '#'s for a h2 header</h2>
|
|
<h6>Six '#'s for a h6 header</h6>
|
|
<h3><strong>Author Notes/Comments</strong></h3>
|
|
<p>Add some hidden notes/comments to your article with this syntax:</p>
|
|
<pre><!-- This won't show up in the content! --></pre>
|
|
<h2 style="font-size:2.8em" id="liquidtags"><strong>🌊 Liquid Tags</strong></h2>
|
|
<p>We support native
|
|
<a href="https://shopify.github.io/liquid" target="_blank" rel="noopener">Liquid tags</a> in our editor, but have created our own custom tags listed below:
|
|
</p>
|
|
<h3><strong><%= community_name %> Article/Post Embed</strong></h3>
|
|
<p>All you need is the full link of the article:</p>
|
|
<code>{% link https://dev.to/kazz/boost-your-productivity-using-markdown-1be %}</code>
|
|
<p>You can also use the slug like this:</p>
|
|
<code>{% link kazz/boost-your-productivity-using-markdown-1be %}</code>
|
|
<p>You can also use the alias post instead of link like this:</p>
|
|
<code>{% post https://dev.to/kazz/boost-your-productivity-using-markdown-1be %}</code>
|
|
<p>or this:</p>
|
|
<code>{% post kazz/boost-your-productivity-using-markdown-1be %}</code>
|
|
<h3><strong><%= community_name %> User Embed</strong></h3>
|
|
<p>All you need is the <%= community_name %> username:</p>
|
|
<code>{% user jess %}</code>
|
|
<h3><strong><%= community_name %> Tag Embed</strong></h3>
|
|
<p>All you need is the tag name:</p>
|
|
<code>{% tag git %}</code>
|
|
<h3><strong><%= community_name %> Comment Embed</strong></h3>
|
|
<p>All you need is the
|
|
<code>ID</code> at the end of a comment URL. To get the comment link, click either the timestamp or the menu button in the top right corner on a comment and then click "Permalink". Here's an example:
|
|
</p>
|
|
<code>{% comment 2d1a %}</code>
|
|
<h3><strong><%= community_name %> Podcast Episode Embed</strong></h3>
|
|
<p>All you need is the full link of the podcast episode:</p>
|
|
<code>{% podcast https://dev.to/basecspodcast/s2e2--queues-irl %}</code>
|
|
<h3><strong><%= community_name %> Listing Embed</strong></h3>
|
|
<p>All you need is the full link of the listing:</p>
|
|
<code>{% listing https://dev.to/listings/collabs/dev-is-open-source-823 %}</code>
|
|
<p>You can also use the category and slug like this:</p>
|
|
<code>{% listing collabs/dev-is-open-source-823 %}</code>
|
|
<p>Note: Expired listings will raise an error. Make sure the listing is published or recently bumped.</p>
|
|
<h3><strong>Twitter Embed</strong></h3>
|
|
<p>Using the Twitter Liquid tag will allow the tweet to pre-render from the server, providing your reader with a better experience. All you need is the tweet
|
|
<code>id</code> from the url.</p>
|
|
<code>{% twitter 834439977220112384 %}</code>
|
|
<h3><strong>Glitch embed</strong></h3>
|
|
<p>All you need is the Glitch project slug</p>
|
|
<code>{% glitch earthy-course %}</code>
|
|
<p>There are several
|
|
<a href="https://glitch.com/help/how-can-i-customize-a-glitch-app-embed">optional attributes</a> you can use in your tag, just add them after the id, separated by spaces.
|
|
</p>
|
|
<dl>
|
|
<dt><code>app</code></dt>
|
|
<dd>
|
|
Shows the app preview without the code.<br>
|
|
<code>{% glitch earthy-course app %}</code>
|
|
</dd>
|
|
<dt><code>code</code></dt>
|
|
<dd>
|
|
Shows the code without the app preview.<br>
|
|
<code>{% glitch earthy-course code %}</code>
|
|
</dd>
|
|
<dt><code>preview-first</code></dt>
|
|
<dd>
|
|
Swap panes: Show the app preview on the left and the code on the right.<br>
|
|
<code>{% glitch earthy-course preview-first %}</code>
|
|
</dd>
|
|
<dt><code>no-attribution</code></dt>
|
|
<dd>
|
|
Hides the avatar of the creator(s).<br>
|
|
<code>{% glitch earthy-course no-attribution %}</code>
|
|
</dd>
|
|
<dt><code>no-files</code></dt>
|
|
<dd>
|
|
Hides the file browser.<br>
|
|
<code>{% glitch earthy-course no-files %}</code>
|
|
</dd>
|
|
<dt><code>file</code></dt>
|
|
<dd>
|
|
Lets you choose which file to display in the code panel. Defaults to index.html.<br>
|
|
<code>{% glitch earthy-course file=script.js %}</code>
|
|
</dd>
|
|
</dl>
|
|
<h3><strong>GitHub Repo Embed</strong></h3>
|
|
<p>All you need is the GitHub username and repo:</p>
|
|
<code>{% github thepracticaldev/dev.to %}</code>
|
|
<dl>
|
|
<dt><code>no-readme</code></dt>
|
|
<dd>
|
|
You can add a no-readme option to your GitHub tag to hide the readme file from the preview.<br>
|
|
<code>{% github thepracticaldev/dev.to no-readme %}</code>
|
|
</dd>
|
|
</dl>
|
|
<h3><strong>GitHub Issue, Pull request or Comment Embed</strong></h3>
|
|
<p>All you need is the GitHub issue, PR or comment URL:</p>
|
|
<code>{% github https://github.com/thepracticaldev/dev.to/issues/9 %}</code>
|
|
<h3><strong>GitHub Gist Embed</strong></h3>
|
|
<p>All you need is the gist link:</p>
|
|
<code>
|
|
{% gist https://gist.github.com/CristinaSolana/1885435 %}
|
|
</code>
|
|
<dl>
|
|
<dt><code>Single File Embed</code></dt>
|
|
<dd>
|
|
<p>You can choose to embed a single gist file. <br>
|
|
<code>{% gist https://gist.github.com/CristinaSolana/1885435 file=gistfile1.md %}</code></p>
|
|
</dd>
|
|
<dt><code>Specific Version Embed</code></dt>
|
|
<dd>
|
|
<p>You can choose to embed a specific version of a gist file. All you need
|
|
the link and the commit hash for that specific version. <br>
|
|
The format is <code>{% gist [gist-link]/[commit-hash] %}</code> <br>
|
|
e.g. <br>
|
|
<code>{% gist https://gist.github.com/suntong/3a31faf8129d3d7a380122d5a6d48ff6/f77d01e82defbf736ebf4879a812cf9c916a9252 %}</code></p>
|
|
</dd>
|
|
<dt><code>Specific Version File Embed</code></dt>
|
|
<dd>
|
|
<p>You can choose to embed a specific version of a gist file. All you need
|
|
the link, the filename and the commit hash for that specific version . <br>
|
|
The format is <code>{% gist [gist-link]/[commit-hash] file=[filename] %}</code> <br>
|
|
e.g. <br>
|
|
<code>
|
|
{% gist https://gist.github.com/suntong/3a31faf8129d3d7a380122d5a6d48ff6/f77d01e82defbf736ebf4879a812cf9c916a9252 file=Images.tmpl %}
|
|
</code></p>
|
|
</dd>
|
|
</dl>
|
|
<h3><strong>GitPitch Embed</strong></h3>
|
|
<p>All you need is the GitPitch link:</p>
|
|
<code>
|
|
{% gitpitch https://gitpitch.com/gitpitch/in-60-seconds %}
|
|
</code>
|
|
<h3><strong>Video Embed</strong></h3>
|
|
<p>All you need is the <code>id</code> from the URL.
|
|
<ul>
|
|
<li><strong>YouTube:</strong> <code>{% youtube dQw4w9WgXcQ %}</code></li>
|
|
<li><strong>Vimeo:</strong> <code>{% vimeo 193110695 %}</code></li>
|
|
</ul>
|
|
<h3><strong>Medium Embed</strong></h3>
|
|
<p>Just enter the full URL of the Medium article you are trying to embed.</p>
|
|
<code>{% medium https://medium.com/s/story/boba-science-how-can-i-drink-a-bubble-tea-to-ensure-that-i-dont-finish-the-tea-before-the-bobas-7fc5fd0e442d %}</code>
|
|
<h3><strong>SlideShare Embed</strong></h3>
|
|
<p>All you need is the SlideShare <code>key</code>:</p>
|
|
<code>{% slideshare rdOzN9kr1yK5eE %}</code>
|
|
<h3><strong>CodePen Embed</strong></h3>
|
|
<p>All you need is the full CodePen <code>link</code>, ending in the pen ID code, as follows:</p>
|
|
<code>{% codepen https://codepen.io/twhite96/pen/XKqrJX %}</code>
|
|
<dl>
|
|
<dt><code>default-tab</code></dt>
|
|
<dd>
|
|
Add default-tab parameter to your CodePen embed tag. Default to <i>result</i><br>
|
|
<code>{% codepen https://codepen.io/twhite96/pen/XKqrJX default-tab=js,result %}</code>
|
|
</dd>
|
|
</dl>
|
|
<h3><strong>Kotlin Playground</strong></h3>
|
|
<p>To create a runnable kotlin snippet, create a Kotlin Snippet at <a href="https://play.kotlinlang.org">https://play.kotlinlang.org</a></p>
|
|
<p>Go to <code>Share</code> dialog and copy the full <code>link</code> from the <code>Medium</code> tab. Use it as follows:</p>
|
|
<code>{% kotlin https://pl.kotl.in/owreUFFUG?theme=darcula&from=3&to=6&readOnly=true %}</code>
|
|
<h3><strong>RunKit Embed</strong></h3>
|
|
<p>Put executable code within a runkit liquid block, as follows:</p>
|
|
<pre>{% runkit<br>// hidden setup JavaScript code goes in this preamble area<br>const hiddenVar = 42<br>%}<br>// visible, reader-editable JavaScript code goes here<br>console.log(hiddenVar)<br>{% endrunkit %}<br></pre>
|
|
|
|
<h3><strong>KaTeX Embed</strong></h3>
|
|
<p>Place your mathematical expression within a KaTeX liquid block, as follows:</p>
|
|
<pre>{% katex %}<br> c = \pm\sqrt{a^2 + b^2}<br>{% endkatex %}<br></pre>
|
|
<p>To render KaTeX inline add the "inline" option:</p>
|
|
<pre>{% katex inline %}<br> c = \pm\sqrt{a^2 + b^2}<br>{% endkatex %}<br></pre>
|
|
|
|
<h3><strong>Stackblitz Embed</strong></h3>
|
|
<p>All you need is the ID of the Stackblitz:</p>
|
|
<code>{% stackblitz ball-demo %}</code>
|
|
<dl>
|
|
<dt><code>Default view</code></dt>
|
|
<dd>
|
|
You can change the default view, the options are <i>both</i>, <i>preview</i>, <i>editor</i>. Defaults to
|
|
<i>both</i><br>
|
|
<code>{% stackblitz ball-demo view=preview %}</code>
|
|
</dd>
|
|
<dt><code>Default file</code></dt>
|
|
<dd>
|
|
You can change the default file you want your embed to point to<br>
|
|
<code>{% stackblitz ball-demo file=style.css %}</code>
|
|
</dd>
|
|
<h3><strong>CodeSandbox Embed</strong></h3>
|
|
<p>All you need is the ID of the Sandbox:</p>
|
|
<code>{% codesandbox ppxnl191zx %}</code>
|
|
<p>Of CodeSandbox's many
|
|
<a href="https://codesandbox.io/docs/embedding#embed-options">optional attributes</a>, the following are supported by using them in your tag, just add them after the id, separated by spaces.
|
|
</p>
|
|
<dl>
|
|
<dt><code>initialpath</code></dt>
|
|
<dd>
|
|
Which url to initially load in address bar.<br>
|
|
<code>{% codesandbox ppxnl191zx initialpath=/initial/load/path %}</code>
|
|
</dd>
|
|
<dt><code>module</code></dt>
|
|
<dd>
|
|
Which module to open by default.<br>
|
|
<code>{% codesandbox ppxnl191zx module=/path/to/module %}</code>
|
|
</dd>
|
|
<dt><code>runonclick</code></dt>
|
|
<dd>
|
|
Delays when code is ran if <code>1</code> <br>
|
|
<code>{% codesandbox ppxnl191zx runonclick=1 %}</code>
|
|
</dd>
|
|
</dl>
|
|
<h3><strong>JSFiddle Embed</strong></h3>
|
|
<p>All you need is the full JSFiddle <code>link</code>, ending in the fiddle ID code, as follows:</p>
|
|
<code>{% jsfiddle https://jsfiddle.net/link2twenty/v2kx9jcd %}</code>
|
|
<dl>
|
|
<dt><code>Custom tabs</code></dt>
|
|
<dd>
|
|
You can add a custom tab order to you JSFiddle embed tag. Defaults to <i>js,html,css,result</i><br>
|
|
<code>{% jsfiddle https://jsfiddle.net/webdevem/Q8KVC result,html,css %}</code>
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3><strong>JSitor Liquid Tag</strong></h3>
|
|
<p>
|
|
To use JSitor liquid tag you can use the JSitor full <code>link</code>, with or without the parameters
|
|
</p>
|
|
<code>{% jsitor https://jsitor.com/embed/B7FQ5tHbY %}</code>
|
|
<br/>
|
|
<code>{% jsitor https://jsitor.com/embed/B7FQ5tHbY?html&js&css&result&light %}</code>
|
|
<p>
|
|
Other options to use JSitor liquid tag is just by its ID, you can add it with or without the parameters
|
|
</p>
|
|
<code>{% jsitor B7FQ5tHbY %}</code>
|
|
<br/>
|
|
<code>{% jsitor B7FQ5tHbY?html&js&css&result&light %}</code>
|
|
|
|
<h3><strong>repl.it Embed</strong></h3>
|
|
<p>All you need is the URL after the domain name:</p>
|
|
<code>{% replit @WigWog/PositiveFineOpensource %}</code>
|
|
<h3><strong>Next Tech Embed</strong></h3>
|
|
<p>All you need is the share URL for your sandbox. You can get the share URL by clicking
|
|
the "Share" button in the top right when the sandbox is open.</p>
|
|
<p><img src="https://thepracticaldev.s3.amazonaws.com/i/r449xp8cay3383i139qv.png" alt="Share Replit sandbox" /></p>
|
|
<code>{% nexttech https://nt.dev/s/6ba1fffbd09e %}</code>
|
|
<h3><strong>Instagram Embed</strong></h3>
|
|
<p>All you need is the Instagram post <code>id</code> from the URL:</p>
|
|
<code>{% instagram BXgGcAUjM39 %}</code>
|
|
<h3><strong>Speakerdeck Tag</strong></h3>
|
|
<p>All you need is the data-id code from the embed link:</p>
|
|
<pre><span style="color: gray;"># Given this embed link:</span><br><script async class="speakerdeck-embed"<br> data-id="<span style='color: orange;'>7e9f8c0fa0c949bd8025457181913fd0</span>"<br> data-ratio="1.77777777777778" src="//speakerdeck.com/assets/embed.js"></script></pre>
|
|
<pre>{% speakerdeck <span style="color: orange;">7e9f8c0fa0c949bd8025457181913fd0</span> %}</pre>
|
|
<h3><strong>Soundcloud Embed</strong></h3>
|
|
<p>Just enter the full URL of the Soundcloud track you are trying to embed.</p>
|
|
<code>{% soundcloud https://soundcloud.com/user-261265215/dev-to-review-episode-1 %}</code>
|
|
<h3><strong>Spotify Embed</strong></h3>
|
|
<p>
|
|
Enter the Spotify URI of the Spotify track / playlist /
|
|
album / artist / podcast episode you are trying to embed.
|
|
</p>
|
|
<pre>{% spotify <span style="color: #1DB954;">spotify:episode:5V4XZWqZQJvbddd31n56mf</span> %}</pre>
|
|
<h3><strong>Blogcast Tag</strong></h3>
|
|
<p>All you need is the article id code from the embed code:</p>
|
|
<pre>{% blogcast <span style="color: orange;">1234</span> %}</pre>
|
|
<h3><strong>Parler Tag</strong></h3>
|
|
<p>Enter the full url of the Parler.io audio file you want to embed. </p>
|
|
<pre>{% parler https://www.parler.io/audio/73240183203/d53cff009eac2ab1bc9dd8821a638823c39cbcea.7dd28611-b7fc-4cf8-9977-b6e3aaf644a1.mp3 %}</pre>
|
|
<h3><strong>Stack Exchange / Stack Overflow Tag</strong></h3>
|
|
<p>
|
|
You'll need the question or answer's ID code, and the site. When using <code>{% stackoverflow %}</code> as the tag, the site will default to Stack Overflow.
|
|
For example:
|
|
<br>
|
|
<a href="https://stackoverflow.com/questions/24789130/colors-in-irb-rails-console">https://stackoverflow.com/questions/24789130/colors-in-irb-rails-console</a>
|
|
<ul>
|
|
<li>The question ID is: <code style="color: aquamarine; background-color: black;">24789130</code></li>
|
|
</ul>
|
|
<pre>{% stackoverflow <span style="color: aquamarine;">24789130</span> %}</pre>
|
|
</p>
|
|
<p>
|
|
For other Stack Exchange network sites, you'll need to provide the site's name and use <code>{% stackexchange %}</code> as the tag. For example:
|
|
<br>
|
|
<a href="https://diy.stackexchange.com/questions/169988/base-for-refrigerator-wine-shelf">https://diy.stackexchange.com/questions/169988/base-for-refrigerator-wine-shelf</a>
|
|
<ul>
|
|
<li>The question ID is: <code style="color: aquamarine; background-color: black;">169988</code></li>
|
|
<li>The site is <code style="color: orange; background-color: black;">diy</code></li>
|
|
</ul>
|
|
<pre>{% stackexchange <span style="color: aquamarine;">169988</span> <span style="color: orange;">diy</span> %}</pre>
|
|
</p>
|
|
<p>
|
|
For answers, you can get the answer's ID code by from the answer's "Share" link. For example:
|
|
<br>
|
|
<a href="https://diy.stackexchange.com/a/170185">https://diy.stackexchange.com/a/170185</a>
|
|
<ul>
|
|
<li>The answer ID is: <code style="color: aquamarine; background-color: black;">170185</code></li>
|
|
<li>The site is <code style="color: orange; background-color: black;">diy</code></li>
|
|
</ul>
|
|
<pre>{% stackexchange <span style="color: aquamarine;">170185</span> <span style="color: orange;">diy</span> %}</pre>
|
|
</p>
|
|
<h3><strong>Wikipedia Embed</strong></h3>
|
|
<p>Enter the full URL of the Wikipedia article you want to embed, with or without the anchor.</p>
|
|
<p>
|
|
<code>{% wikipedia https://en.wikipedia.org/wiki/Wikipedia %}</code>
|
|
<br/>
|
|
<code>{% wikipedia https://en.wikipedia.org/wiki/Wikipedia#Diversity %}</code>
|
|
</p>
|
|
<h3><strong>Asciinema Embed</strong></h3>
|
|
<p>All you need is an Asciinema id or URL:</p>
|
|
<code>{% asciinema 239367 %}</code>
|
|
<code>{% asciinema https://asciinema.org/a/239367 %}</code>
|
|
|
|
<h3><strong>Reddit Tag</strong></h3>
|
|
<p>Enter the full URL of the post you want to embed</p>
|
|
<pre>
|
|
{% reddit https://www.reddit.com/r/aww/comments/ag3s4b/ive_waited_28_years_to_finally_havr_my_first_pet %}
|
|
</pre>
|
|
|
|
<h3><strong>Parsing Liquid Tags as a Code Example</strong></h3>
|
|
<p>To parse Liquid tags as code, simply wrap it with a single backtick or triple backticks.</p>
|
|
<p><code>`{% mytag %}{{ site.SOMETHING }}{% endmytag %}`</code></p>
|
|
<p>One specific edge case is with using the <code>raw</code> tag. To properly escape it, use this format:
|
|
</p>
|
|
<p><code>`{% raw %}{{site.SOMETHING }} {% ``endraw`` %}`</code></p>
|
|
<h3><strong>Common Gotchas</strong></h3>
|
|
<p>
|
|
Lists are written just like any other Markdown editor.
|
|
If you're adding an image in between numbered list, though, be sure to tab the image,
|
|
otherwise it'll restart the number of the list.
|
|
Here's an example of what to do:
|
|
<img src="https://res.cloudinary.com/practicaldev/image/fetch/s--HjVUshkb--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://thepracticaldev.s3.amazonaws.com/i/8l29vxiir8k5d097o9o8.png"
|
|
alt="example image of writing lists with images in Markdown">
|
|
</p>
|
|
<h4>
|
|
<a href="https://github.com/adam-p/markdown-here/wiki/Markdown-Here-Cheatsheet" target="_blank" rel="noopener">Here's the Markdown cheatsheet again for reference.</a>
|
|
</h4>
|
|
Happy posting! 📝
|
|
<br>
|
|
<br>
|
|
<div class="blank-space"></div>
|
|
</div>
|
|
</div>
|