docbrown/app/views/pages/_editor_guide_text.en.html.erb

<style>
  .permalink-heading svg {
    fill: currentColor;
    visibility: hidden;
  }

  .permalink-heading a:focus svg,
  .permalink-heading:hover svg {
    visibility: visible;
  }

  .container .body pre {
    margin-bottom: 1em;
  }
</style>

<main class="container article" id="editor-help-guide">
  <article id="main-content" class="body">
    <h1 style="font-size: 57px; font-weight: 700; line-height: 73px;">Editor Guide 🤓</h1>

    <% if version == "1" %>
      <%= render "pages/v1_editor_guide_preamble" %>
    <% else %>
      <p>
        <em>
          <strong>Our editor has two versions</strong>.
          If you prefer Jekyll-style "frontmatter", switch to "basic markdown" in
          <a href="<%= user_settings_path(:customization) %>">Settings → Customization</a>.
        </em>
      </p>

      <h2 style="font-size:2.8em" id="#things-to-know" class="permalink-heading">
        <strong>Things to Know</strong>
        <a href="#things-to-know" aria-label="permalink for Things to know">
          <%= crayons_icon_tag("small-link", aria_hidden: true) %>
        </a>
      </h2>
      <ul>
        <li>Use <a href="#markdown"><strong>markdown</strong></a> to write and format <a href="<%= root_path %>"><%= 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" class="permalink-heading">
      <strong>✍ Markdown Basics</strong>
      <a href="#markdown" aria-label="permalink for Markdown">
        <%= crayons_icon_tag("small-link", aria_hidden: true) %>
      </a>
    </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>

    <%= render partial: "editor_guide_h3", locals: { id: "markdown-bold-and-italic", title: "Bold & Italic" } %>
    <p><em>Italics</em>: <code>*asterisks*</code> or <code>_underscores_</code></p>
    <p><strong>Bold</strong>: <code>**double asterisks**</code> or <code>__double underscores__</code></p>

    <%= render partial: "editor_guide_h3", locals: { id: "markdown-links", title: "Links" } %>
    <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>

    <%= render partial: "editor_guide_h3", locals: { id: "markdown-inline-images", title: "Inline Images" } %>
    <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" loading="lazy" />
    </p>
    <pre>![Image description](put-link-to-image-here)</pre>
    <figure>
        <img src="https://res.cloudinary.com/practicaldev/image/fetch/s--OsLaFSo9--/c_fill,f_auto,fl_progressive,h_50,q_auto,w_50/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/31047/af153cd6-9994-4a68-83f4-8ddf3e13f0bf.jpg" alt="example image, with sloan" loading="lazy" />
        <figcaption>You can even add a caption using the HTML <code>figcaption</code> tag!</figcaption>
    </figure>

    <%= render partial: "editor_guide_h3", locals: { id: "markdown-headers", title: "Headings" } %>
    <p>Add a heading to your post with this syntax:</p>
    <pre># One '#' for a h1 heading<br>## Two '#'s for a h2 heading<br>...<br>###### Six '#'s for a h6 heading</pre>

    <%= render partial: "editor_guide_h3", locals: { id: "author-notes", title: "Author Notes/Comments" } %>
    <p>Add some hidden notes/comments to your article with this syntax:</p>
    <pre>&lt;!-- This won't show up in the content! --&gt;</pre>

    <h2 style="font-size:2.8em" id="accessibility" class="permalink-heading">
      <strong>Accessibility</strong>
      <a href="#accessibility" aria-label="permalink for Accessibility"><%= crayons_icon_tag("small-link", aria_hidden: true) %></a>
    </h2>
    <p>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 <a href="https://www.w3.org/WAI/fundamentals/accessibility-intro/">W3C's Introduction to Web Accessibility</a>, 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.</p>

    <%= render partial: "editor_guide_h3", locals: { id: "alt-text-for-images", title: "Providing alternative descriptions for images" } %>
    <p>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.</p>
    <p>When you upload an image in the editor, you will see the following text to copy and paste into your post:</p>
    <pre>![Image description](/file-path/my-image.png)</pre>
    <p>Replace the "Image description" in square brackets with a description of your image - for example:</p>
    <pre>![A pie chart showing 40% responded "Yes", 50% responded "No" and 10% responded "Not sure"](/file-path/my-image.png)</pre>
    <p>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.</p>

    <%= render partial: "editor_guide_h3", locals: { id: "accessible-headings", title: "Providing headings" } %>
    <p>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.</p>
    <p><a href="#markdown-headers">Headings can be added in levels 1 - 6</a>. 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.</p>
    <p>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:</p>
    <pre>## Fun facts about sloths</br></br>### Speed</br></br>Sloths move at a maximum speed of 0.27 km/h!</pre>

    <%= render partial: "liquid_tag_section_intro", locals: { styles: "font-size:2.8em;" } %>

    <%= render partial: "editor_guide_h3", locals: { id: "supported-url-embeds-list", title: "Supported URL Embeds" } %>

    <%= render partial: "supported_url_embeds_list" %>

    <%= render partial: "editor_guide_h3", locals: { id: "supported-nonurl-embeds-list", title: "Supported Non-URL Embeds" } %>

    <%= render partial: "supported_nonurl_embeds_list" %>

    <%= render partial: "editor_guide_h3", locals: { id: "parsing-liquid-tags-as-code-example", title: "Parsing Liquid Tags as a Code Example" } %>
    <p>To parse Liquid tags as code, simply wrap it with a single backtick or triple backticks.</p>
    <pre>`{% mytag %}{{ site.SOMETHING }}{% endmytag %}`</pre>
    <p>One specific edge case is with using the <code>raw</code> tag. To properly escape it, use this format:
    </p>
    <pre>`{% raw %}{{site.SOMETHING }} {% ``endraw`` %}`</pre>

    <%= render partial: "editor_guide_h3", locals: { id: "common-gotchas", title: "Common Gotchas" } %>
    <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"
        loading="lazy" />
    </p>

    <p>
      <a href="https://github.com/adam-p/markdown-here/wiki/Markdown-Here-Cheatsheet" target="_blank" rel="noopener">
        <strong>Here's the Markdown cheatsheet again for reference.</strong>
      </a>
    </p>

    <p>Happy posting! 📝</p>
  </article>
</main>