Editor Guide 🤓

Things to Know

Use markdown to write and format Migdal posts.
Most of the time, you can write inline HTML directly into your posts.
You can use Liquid tags to make add rich content such as tweets and videos.
Links to unpublished posts are shareable for feedback/review.
The best size for your cover image is 1000 X 420.

✍ Markdown Basics

Below are some examples of commonly used markdown syntax. If you want to dive deeper, check out this cheat sheet.

Bold & Italic

Italics: *asterisks* or _underscores_

Bold: **double asterisks** or __double underscores__

Links

I'm an inline link: [I'm an inline link](put-link-here)

Anchored links (For things like a Table of Contents)

      ## Table Of Contents
        * [Chapter 1](#chapter-1)
        * [Chapter 2](#chapter-2)

      ### Chapter 1 <a name="chapter-1"></a>

Inline Images

When adding GIFs to posts and comments, please note that there is a limit of 200 megapixels per frame/page. example image, with sloan

![Image description](put-link-to-image-here)

Headings

Add a heading to your post with this syntax:

# One '#' for a h1 heading
## Two '#'s for a h2 heading
...
###### Six '#'s for a h6 heading

Author Notes/Comments

Add some hidden notes/comments to your article with this syntax:

<!-- This won't show up in the content! -->

Accessibility

People access online content in all kinds of different ways, and there are a few things you can do to make your posts more easily understood by a broad range of users. You can find out more about web accessibility at W3C's Introduction to Web Accessibility, but there are two main ways you can make your posts more accessible: providing alternative descriptions of any images you use, and adding appropriate headings.

Providing alternative descriptions for images

Some users might not be able to see or easily process images that you use in your posts. Providing an alternative description for an image helps make sure that everyone can understand your post, whether they can see the image or not.

When you upload an image in the editor, you will see the following text to copy and paste into your post:

![Image description](/file-path/my-image.png)

Replace the "Image description" in square brackets with a description of your image - for example:

![A pie chart showing 40% responded "Yes", 50% responded "No" and 10% responded "Not sure"](/file-path/my-image.png)

By doing this, if someone reads your post using an assistive device like a screen reader (which turns written content into spoken audio) they will hear the description you entered.

Providing headings

Headings provide an outline of your post to readers, including people who can't see the screen well. Many assistive technologies (like screen readers) allow users to skip directly to a particular heading, helping them find and understand the content of your post with ease.

Headings can be added in levels 1 - 6. Avoid using a level one heading (i.e., '# Heading text'). When you create a post, your post title automatically becomes a level one heading and serves a special role on the page, much like the headline of a newspaper article. Similar to how a newspaper article only has one headline, it can be confusing if multiple level one headings exist on a page.

In your post content, start with level two headings for each section (e.g. '## Section heading text'), and increase the heading level by one when you'd like to add a sub-section, for example:

## Fun facts about sloths

### Speed

Sloths move at a maximum speed of 0.27 km/h!

🌊 Liquid Tags

We support native Liquid tags in our editor, but have created our own custom tags listed below:

Migdal Article/Post Embed

All you need is the full link of the article:

{% link https://migdal.jp/kazz/boost-your-productivity-using-markdown-1be %}

You can also use the slug like this:

{% link kazz/boost-your-productivity-using-markdown-1be %}

You can also use the alias post instead of link like this:

{% post https://migdal.jp/kazz/boost-your-productivity-using-markdown-1be %}

or this:

{% post kazz/boost-your-productivity-using-markdown-1be %}

Migdal User Embed

All you need is the Migdal username:

{% user jess %}

Migdal Tag Embed

All you need is the tag name:

{% tag git %}

Migdal Comment Embed

All you need is the ID 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:

{% comment 2d1a %}

Migdal Podcast Episode Embed

All you need is the full link of the podcast episode:

{% podcast https://migdal.jp/basecspodcast/s2e2--queues-irl %}

Migdal Listing Embed

All you need is the full link of the listing:

{% listing https://migdal.jp/listings/collabs/dev-is-open-source-823 %}

You can also use the category and slug like this:

{% listing collabs/dev-is-open-source-823 %}

Note: Expired listings will raise an error. Make sure the listing is published or recently bumped.

Details Embed

You can embed a details HTML element by using details, spoiler, or collapsible. The summary will be what the dropdown title displays. The content will be the text hidden behind the dropdown. This is great for when you want to hide text (i.e. answers to questions) behind a user action/intent (i.e. a click).

      {% details summary %} content {% enddetails %}
      {% spoiler summary %} content {% endspoiler %}
      {% collapsible summary %} content {% endcollapsible %}

Twitter Embed

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 id from the url.

{% twitter 834439977220112384 %}

Twitter Timeline

Using the Twitter Timeline Liquid tag will allow the Twitter Timeline to pre-render from the server. All you need is the Twitter Timeline link.

{% twitter_timeline https://twitter.com/username/timelines/834439977220112384 %}

Glitch Embed

All you need is the Glitch project slug

{% glitch earthy-course %}

There are several optional attributes you can use in your tag, just add them after the id, separated by spaces.

app

Shows the app preview without the code.

{% glitch earthy-course app %}

code

Shows the code without the app preview.

{% glitch earthy-course code %}

preview-first

Swap panes: Show the app preview on the left and the code on the right.

{% glitch earthy-course preview-first %}

no-attribution

Hides the avatar of the creator(s).

{% glitch earthy-course no-attribution %}

no-files

Hides the file browser.

{% glitch earthy-course no-files %}

file

Lets you choose which file to display in the code panel. Defaults to index.html.

{% glitch earthy-course file=script.js %}

GitHub Repository Embed

All you need is the GitHub username and the repository name:

{% github forem/forem %}

no-readme

You can add a no-readme option to your GitHub tag to hide the readme file from the preview.

{% github forem/forem no-readme %}

GitHub Issue, Pull Request or Comment Embed

All you need is the GitHub issue, pull request or comment URL:

{% github https://github.com/forem/forem/issues/9 %}

GitHub Gist Embed

All you need is the gist link:

{% gist https://gist.github.com/CristinaSolana/1885435 %}

Single File Embed

You can choose to embed a single gist file.

{% gist https://gist.github.com/CristinaSolana/1885435 file=gistfile1.md %}

Specific Version Embed

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. The format is {% gist [gist-link]/[commit-hash] %}

{% gist https://gist.github.com/suntong/3a31faf8129d3d7a380122d5a6d48ff6/f77d01e82defbf736ebf4879a812cf9c916a9252 %}

Specific Version File Embed

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. The format is {% gist [gist-link]/[commit-hash] file=[filename] %}

{% gist https://gist.github.com/suntong/3a31faf8129d3d7a380122d5a6d48ff6/f77d01e82defbf736ebf4879a812cf9c916a9252 file=Images.tmpl %}

GitPitch Embed

All you need is the GitPitch link:

{% gitpitch https://gitpitch.com/gitpitch/in-60-seconds %}

Video Embed

All you need is the id from the URL.

YouTube: {% youtube dQw4w9WgXcQ %}
Vimeo: {% vimeo 193110695 %}
Twitch: {% twitch ClumsyPrettiestOilLitFam %}

Medium Embed

Just enter the full URL of the Medium article you are trying to embed.

{% 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 %}

SlideShare Embed

All you need is the SlideShare key:

{% slideshare rdOzN9kr1yK5eE %}

CodePen Embed

All you need is the full CodePen link, ending in the pen ID code, as follows:

{% codepen https://codepen.io/twhite96/pen/XKqrJX %}

default-tab

Add default-tab parameter to your CodePen embed tag. Defaults to result.

{% codepen https://codepen.io/twhite96/pen/XKqrJX default-tab=js,result %}

Kotlin Playground

To create a runnable kotlin snippet, create a Kotlin Snippet at https://play.kotlinlang.org

Go to Share dialog and copy the full link from the Medium tab. Use it as follows:

{% kotlin https://pl.kotl.in/owreUFFUG?theme=darcula&from=3&to=6&readOnly=true %}

RunKit Embed

Put executable code within a runkit liquid block, as follows:

{% runkit
// hidden setup JavaScript code goes in this preamble area
const hiddenVar = 42
%}
// visible, reader-editable JavaScript code goes here
console.log(hiddenVar)
{% endrunkit %}

KaTeX Embed

Place your mathematical expression within a KaTeX liquid block, as follows:

{% katex %}
 c = \pm\sqrt{a^2 + b^2}
{% endkatex %}

To render KaTeX inline add the "inline" option:

{% katex inline %}
 c = \pm\sqrt{a^2 + b^2}
{% endkatex %}

Stackblitz Embed

All you need is the ID of the Stackblitz:

{% stackblitz ball-demo %}

Default view

You can change the default view, the options are both, preview, editor. Defaults to both

{% stackblitz ball-demo view=preview %}

Default file

You can change the default file you want your embed to point to

{% stackblitz ball-demo file=style.css %}

CodeSandbox Embed

All you need is the ID of the sandbox:

{% codesandbox ppxnl191zx %}

Of CodeSandbox's many optional attributes, the following are supported by using them in your tag, just add them after the id, separated by spaces:

initialpath

Which url to initially load in address bar.

{% codesandbox ppxnl191zx initialpath=/initial/load/path %}

module

Which module to open by default.

{% codesandbox ppxnl191zx module=/path/to/module %}

runonclick

Delays when code is ran if 1

{% codesandbox ppxnl191zx runonclick=1 %}

JSFiddle Embed

All you need is the full JSFiddle link, ending in the fiddle ID code, as follows:

{% jsfiddle https://jsfiddle.net/link2twenty/v2kx9jcd %}

Custom tabs

You can add a custom tab order to you JSFiddle embed tag. Defaults to js,html,css,result.

{% jsfiddle https://jsfiddle.net/webdevem/Q8KVC result,html,css %}

JSitor Liquid Tag

To use JSitor liquid tag you can use the JSitor full link, with or without the parameters

{% jsitor https://jsitor.com/embed/B7FQ5tHbY %}
{% jsitor https://jsitor.com/embed/B7FQ5tHbY?html&js&css&result&light %}

Other options to use JSitor liquid tag is just by its ID, you can add it with or without the parameters:

{% jsitor B7FQ5tHbY %}
{% jsitor B7FQ5tHbY?html&js&css&result&light %}

replit Embed

All you need is the URL after the domain name:

{% replit @WigWog/PositiveFineOpensource %}

Stackery Embed

Visualize your AWS Serverless Application Model templates with Stackery's visualizer embed

All you need is the repository owner, repository name, and branch that you would like visualized

{% stackery deeheber lambda-layer-example master %}

The repository must be a public GitHub repository and have a valid AWS SAM template in the project root titled template.yaml

Next Tech Embed

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.

Share Replit sandbox

{% nexttech https://nt.dev/s/6ba1fffbd09e %}

Instagram Embed

All you need is the Instagram post id from the URL:

{% instagram BXgGcAUjM39 %}

Speakerdeck Tag

All you need is the data-id code from the embed link:

<script async class="speakerdeck-embed"
    data-id="7e9f8c0fa0c949bd8025457181913fd0"
    data-ratio="1.77777777777778" src="//speakerdeck.com/assets/embed.js"></script>

{% speakerdeck 7e9f8c0fa0c949bd8025457181913fd0 %}

SoundCloud Embed

Just enter the full URL of the SoundCloud track you are trying to embed.

{% soundcloud https://soundcloud.com/user-261265215/dev-to-review-episode-1 %}

Spotify Embed

Enter the Spotify URI of the Spotify track / playlist / album / artist / podcast episode you are trying to embed.

{% spotify spotify:episode:5V4XZWqZQJvbddd31n56mf %}

Blogcast Tag

All you need is the article id code from the embed code:

{% blogcast 1234 %}

Parler Tag

Enter the full url of the Parler.io audio file you want to embed.

{% parler https://www.parler.io/audio/73240183203/d53cff009eac2ab1bc9dd8821a638823c39cbcea.7dd28611-b7fc-4cf8-9977-b6e3aaf644a1.mp3 %}

Stack Exchange / Stack Overflow Tag

You'll need the question or answer's ID code, and the site. When using {% stackoverflow %} as the tag, the site will default to Stack Overflow. For example: https://stackoverflow.com/questions/24789130/colors-in-irb-rails-console

The question ID is: 24789130

{% stackoverflow 24789130 %}

For other Stack Exchange network sites, you'll need to provide the site's name and use {% stackexchange %} as the tag. For example: https://diy.stackexchange.com/questions/169988/base-for-refrigerator-wine-shelf

The question ID is: 169988
The site is diy

{% stackexchange 169988 diy %}

For answers, you can get the answer's ID code by from the answer's "Share" link. For example: https://diy.stackexchange.com/a/170185

The answer ID is: 170185
The site is diy

{% stackexchange 170185 diy %}

Wikipedia Embed

Enter the full URL of the Wikipedia article you want to embed, with or without the anchor.

{% wikipedia https://en.wikipedia.org/wiki/Wikipedia %}
{% wikipedia https://en.wikipedia.org/wiki/Wikipedia#Diversity %}

Asciinema Embed

All you need is an Asciinema id or URL:

{% asciinema 239367 %}
{% asciinema https://asciinema.org/a/239367 %}

Reddit Tag

Enter the full URL of the post you want to embed

{% reddit https://www.reddit.com/r/aww/comments/ag3s4b/ive_waited_28_years_to_finally_havr_my_first_pet %}

Parsing Liquid Tags as a Code Example

To parse Liquid tags as code, simply wrap it with a single backtick or triple backticks.

`{% mytag %}{{ site.SOMETHING }}{% endmytag %}`

One specific edge case is with using the raw tag. To properly escape it, use this format:

`{% raw %}{{site.SOMETHING }} {% ``endraw`` %}`

Common Gotchas

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: example image of writing lists with images in Markdown

Here's the Markdown cheatsheet again for reference.

Happy posting! 📝

Migdal は創作言語・世界愛好者の憩いの場です