{"id":778,"date":"2025-09-23T07:16:04","date_gmt":"2025-09-23T07:16:04","guid":{"rendered":"https:\/\/software.sil.org\/bjcree\/?page_id=778"},"modified":"2025-09-23T07:16:04","modified_gmt":"2025-09-23T07:16:04","slug":"markdown-test","status":"publish","type":"page","link":"https:\/\/software.sil.org\/bjcree\/markdown-test\/","title":{"rendered":"Markdown Test"},"content":{"rendered":"<p>This document gives examples of how to use markdown for font documentation, for both in-project docs (html, pdf) and product site page source (md). Although these three target doc types each support some unique capabilities (e.g. product site accordions) this doc focuses on markdown that works for all three types.<\/p>\n<h2>Paragraphs, text formatting, line breaking<\/h2>\n<p>This paragraph gives examples of formatting that uses special enclosing characters: <em>italic<\/em>, <strong>bold<\/strong>, <code>inline code<\/code>.<\/p>\n<p>Here is a second paragraph. If you want to<br \/>\nbreak a line in a specific place the clearest way is to use <code>&lt;br&gt;<\/code>.<\/p>\n<h2>Headings<\/h2>\n<p>Note that H1 is not used for font documentation pages.<\/p>\n<h2>H2<\/h2>\n<p>The H2 is the most common heading type used.<\/p>\n<h3>H3<\/h3>\n<h4>H4<\/h4>\n<h5>H5<\/h5>\n<h6>H6<\/h6>\n<h2>Tables<\/h2>\n<table>\n<thead>\n<tr>\n<th>Unicode block<\/th>\n<th>Font support<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>C0 Controls and Basic Latin<\/td>\n<td>U+0020..U+007E<\/td>\n<\/tr>\n<tr>\n<td>C1 Controls and Latin-1 Supplement<\/td>\n<td>U+00A0..U+00FF<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>When text requires wrapping in cells, the relative width of columns can be somewhat adjusted by tweaking the <code>--- | ---<\/code> line under the header:<\/p>\n<table>\n<thead>\n<tr>\n<th>Unicode block<\/th>\n<th>Characters<\/th>\n<th>Long explanation<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>C0 Controls and Basic Latin<\/td>\n<td>U+0020..U+007E<\/td>\n<td>This is a longer text to describe the basic Latin block<\/td>\n<\/tr>\n<tr>\n<td>C1 Controls and Latin-1 Supplement<\/td>\n<td>U+00A0..U+00FF<\/td>\n<td><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>Table columns can also be aligned using <code>:---:<\/code> syntax:<\/p>\n<table>\n<thead>\n<tr>\n<th align=\"left\">Left-aligned<\/th>\n<th align=\"center\">Centered<\/th>\n<th align=\"right\">Right-aligned<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td align=\"left\">This is a longer text to describe the basic Latin block<\/td>\n<td align=\"center\">C0 Controls and Basic Latin<\/td>\n<td align=\"right\">U+0020..U+007E<\/td>\n<\/tr>\n<tr>\n<td align=\"left\">More left-aligned text<\/td>\n<td align=\"center\">C1 Controls and Latin-1 Supplement<\/td>\n<td align=\"right\">U+00A0..U+00FF<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Lists<\/h2>\n<h3>Ordered List<\/h3>\n<ol>\n<li>First item<\/li>\n<li>Second item<\/li>\n<li>Third item<\/li>\n<\/ol>\n<h3>Unordered List<\/h3>\n<ul>\n<li>List item<\/li>\n<li>Another item<\/li>\n<li>And another item<\/li>\n<\/ul>\n<h3>Nested List<\/h3>\n<ul>\n<li>List item\n<ul>\n<li>Subitem<\/li>\n<li>Another subitem<\/li>\n<\/ul>\n<\/li>\n<li>Another item<\/li>\n<\/ul>\n<h2>Blockquotes<\/h2>\n<blockquote><p>\n  Here is a block quote.<br \/>\n  <strong>Note<\/strong> that you can use <em>Markdown syntax<\/em> within a blockquote.\n<\/p><\/blockquote>\n<h2>Code blocks<\/h2>\n<pre><code>&lt;!DOCTYPE html&gt;\n&lt;html lang=\"en\"&gt;\n&lt;head&gt;\n  &lt;meta charset=\"UTF-8\"&gt;\n  &lt;title&gt;Example HTML5 Document&lt;\/title&gt;\n&lt;\/head&gt;\n&lt;body&gt;\n  &lt;p&gt;Test&lt;\/p&gt;\n&lt;\/body&gt;\n&lt;\/html&gt;\n<\/code><\/pre>\n<h2>Links<\/h2>\n<p>External links always specify the full URL (<a href=\"https:\/\/keyman.com\" target=\"_blank\" rel=\"noopener\">Keyman<\/a>, <a href=\"https:\/\/software.sil.org\">SIL Language Technology<\/a>). Relative links should point to the relevant markdown file (<a href=\"about\">This project\u2019s About page<\/a>).<\/p>\n<p>Links to external  files are a bit odd and require changing the extension in the source to <code>.md<\/code> rather than &#8220;. This prevents the extension changing to <code>.html<\/code>.<\/p>\n<p>Links can be specified inline, with the full link in the text, or using named references (<a href=\"about\">This project\u2019s About page<\/a>).<\/p>\n<h2>Footnotes<\/h2>\n<p>Here is an example of a footnote<sup id=\"fnref-778-1\"><a href=\"#fn-778-1\">1<\/a><\/sup> that will appear at the very bottom<sup id=\"fnref-778-anytext\"><a href=\"#fn-778-anytext\">2<\/a><\/sup> of the page. Footnotes will automatically be numbered sequentially when rendered.<\/p>\n<h2>Images<\/h2>\n<p>Images should be specified in markdown syntax with the local path used as the link. The class is required and needs to be defined in {}, usually {.fullsize}. Then the actual path to the image in the product site image library needs to be placed in a comment using a special syntax. If you want a caption it needs to be placed in a separate html <em>figcaption<\/em> element. Example:<\/p>\n<p><img class='fullsize' alt='Charis SIL Sample - Precomposed Latin Diacritics' src='http:\/\/software.sil.org\/charis\/wp-content\/uploads\/sites\/14\/2015\/12\/CharisSILTypePage.png' \/><br \/>\n<em>This is the caption<\/em><\/p>\n<h2>Web fonts<\/h2>\n<p>To display text in the html and pdf versions using generated fonts a few things need to be in place:<\/p>\n<ul>\n<li>Each font that is used needs to have both <code>@font-face<\/code> and a corresponding class definition in <code>\/documentation\/source\/assets\/css\/webfonts.css<\/code><\/li>\n<li>The WOFF2 fonts used must be manually copied into the local <code>\/web<\/code> folder of whatever machine is used to generate the pdfs. These should ideally not be committed to the project repo. The generated fonts are already automatically in the right place in the user install archive.<\/li>\n<li>The text must be enclosed in a <code>&lt;span&gt;<\/code> with the appropriate class definition.<\/li>\n<li>If the font size needs to be different from the main body text, then the font-size (in rem) needs to be added to the css for that class in either theme.css or webfonts.css. Instead the size can be explicitly set in the individual <code>&lt;span&gt;<\/code><\/li>\n<\/ul>\n<p>In order for text marked up in the same way to display properly on the product sites a few additional things need to be set up:<\/p>\n<ul>\n<li>The WOFF2 font files need to be uploaded to the product site server (see docs elsewhere), and be given reference names to match the font family names used in webfonts.css.<\/li>\n<li>Each page that uses the font needs to have a  shortcode definition that matches the css class id and font family names.<\/li>\n<li>The classes listed in individual <code>&lt;span&gt;<\/code>s need to include &#8216;normal&#8217; to remove any inherited styling. <\/li>\n<\/ul>\n<p>Example: <span class='charis-R normal'>Charis SIL regular,<\/span> <span class='charis-I normal'>italic,<\/span> <span class='charis-B normal'>bold,<\/span> and <span class='charis-BI normal'>bold italic.<\/span><\/p>\n<h2>Font features<\/h2>\n<p>Activating font features requires setting feature values. It is possible to set the font-feature-settings using special css classes, but it may be better to set the feature setting in the <code>&lt;span&gt;<\/code>. This reduces the number of  shortcode definitions that need to be added to each page. Examples:<\/p>\n<table>\n<thead>\n<tr>\n<th>Feature<\/th>\n<th>Default<\/th>\n<th>Activated<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>Small caps (scmp)<\/td>\n<td><span class='charis-R normal'>abcde<\/span><\/td>\n<td><span class='charis-R normal' style='font-feature-settings: \"smcp\"'>abcde<\/span><\/td>\n<\/tr>\n<tr>\n<td>Eng alternate 1 (cv43)<\/td>\n<td><span class='charis-R normal'>\u014a<\/span><\/td>\n<td><span class='charis-R normal' style='font-feature-settings: \"cv43\" 1'>\u014a<\/span><\/td>\n<\/tr>\n<tr>\n<td>Eng alternate 2 (cv43)<\/td>\n<td><span class='charis-R normal'>\u014a<\/span><\/td>\n<td><span class='charis-R normal' style='font-feature-settings: \"cv43\" 2'>\u014a<\/span><\/td>\n<\/tr>\n<tr>\n<td>Eng alternate 3 (cv43)<\/td>\n<td><span class='charis-R normal'>\u014a<\/span><\/td>\n<td><span class='charis-R normal' style='font-feature-settings: \"cv43\" 3'>\u014a<\/span><\/td>\n<\/tr>\n<tr>\n<td>Serbian italic alternates (language-specific)<\/td>\n<td><span class='charis-I normal'>\u0431 \u0433 \u0434 \u043f \u0442<\/span><\/td>\n<td><span class='charis-I normal' lang='sr'>\u0431 \u0433 \u0434 \u043f \u0442<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Right-to-left text<\/h2>\n<p>Embedding spans of right-to-left text within a primarily left-to-right paragraph requires adding <code>dir=\"rtl\"<\/code> to each <code>&lt;span&gt;<\/code>: <span dir=\"rtl\" class='scheherazadenew-R normal'>\u0644\u0643\u0644 \u0634\u062e\u0635 \u0627\u0644\u062d\u0642 \u0641\u064a \u0627\u0644\u062a\u0639\u0644\u0645. \u0648\u064a\u062c\u0628 \u0623\u0646 \u064a\u0643\u0648\u0646 \u0627\u0644\u062a\u0639\u0644\u064a\u0645 \u0641\u064a \u0645\u0631\u0627\u062d\u0644\u0647 \u0627\u0644\u0623\u0648\u0644\u0649 \u0648\u0627\u0644\u0623\u0633\u0627\u0633\u064a\u0629 \u0639\u0644\u0649 \u0627\u0644\u0623\u0642\u0644 \u0628\u0627\u0644\u0645\u062c\u0627\u0646\u060c \u0648\u0623\u0646 \u064a\u0643\u0648\u0646 \u0627\u0644\u062a\u0639\u0644\u064a\u0645 \u0627\u0644\u0623\u0648\u0644\u064a \u0625\u0644\u0632\u0627\u0645\u064a\u0627 \u0648\u064a\u0646\u0628\u063a\u064a \u0623\u0646 \u064a\u0639\u0645\u0645 \u0627\u0644\u062a\u0639\u0644\u064a\u0645 \u0627\u0644\u0641\u0646\u064a \u0648\u0627\u0644\u0645\u0647\u0646\u064a\u060c \u0648\u0623\u0646 \u064a\u064a\u0633\u0631 \u0627\u0644\u0642\u0628\u0648\u0644 \u0644\u0644\u062a\u0639\u0644\u064a\u0645 \u0627\u0644\u0639\u0627\u0644\u064a \u0639\u0644\u0649 \u0642\u062f\u0645 \u0627\u0644\u0645\u0633\u0627\u0648\u0627\u0629 \u0627\u0644\u062a\u0627\u0645\u0629 \u0644\u0644\u062c\u0645\u064a\u0639 \u0648\u0639\u0644\u0649 \u0623\u0633\u0627\u0633 \u0627\u0644\u0643\u0641\u0627\u0621\u0629.  <\/span> The direction changes should just work, even when the text is broken between multiple lines.<\/p>\n<p>Block elements (paragraphs, etc.) that are primarily right-to-left require wrapping each block in the appropriate HTML tag and also adding <code>dir=\"rtl\"<\/code> to each HTML tag (not the <code>&lt;span&gt;<\/code>):<\/p>\n<p dir=\"rtl\"><span class='scheherazadenew-R normal'>\u0644\u0643\u0644 \u0634\u062e\u0635 \u0627\u0644\u062d\u0642 \u0641\u064a \u0627\u0644\u062a\u0639\u0644\u0645. \u0648\u064a\u062c\u0628 \u0623\u0646 \u064a\u0643\u0648\u0646 \u0627\u0644\u062a\u0639\u0644\u064a\u0645 \u0641\u064a \u0645\u0631\u0627\u062d\u0644\u0647 \u0627\u0644\u0623\u0648\u0644\u0649 \u0648\u0627\u0644\u0623\u0633\u0627\u0633\u064a\u0629 \u0639\u0644\u0649 \u0627\u0644\u0623\u0642\u0644 \u0628\u0627\u0644\u0645\u062c\u0627\u0646\u060c \u0648\u0623\u0646 \u064a\u0643\u0648\u0646 \u0627\u0644\u062a\u0639\u0644\u064a\u0645 \u0627\u0644\u0623\u0648\u0644\u064a \u0625\u0644\u0632\u0627\u0645\u064a\u0627 \u0648\u064a\u0646\u0628\u063a\u064a \u0623\u0646 \u064a\u0639\u0645\u0645 \u0627\u0644\u062a\u0639\u0644\u064a\u0645 \u0627\u0644\u0641\u0646\u064a \u0648\u0627\u0644\u0645\u0647\u0646\u064a\u060c \u0648\u0623\u0646 \u064a\u064a\u0633\u0631 \u0627\u0644\u0642\u0628\u0648\u0644 \u0644\u0644\u062a\u0639\u0644\u064a\u0645 \u0627\u0644\u0639\u0627\u0644\u064a \u0639\u0644\u0649 \u0642\u062f\u0645 \u0627\u0644\u0645\u0633\u0627\u0648\u0627\u0629 \u0627\u0644\u062a\u0627\u0645\u0629 \u0644\u0644\u062c\u0645\u064a\u0639 \u0648\u0639\u0644\u0649 \u0623\u0633\u0627\u0633 \u0627\u0644\u0643\u0641\u0627\u0621\u0629.  <\/span><\/p>\n<p>RTL text in table cells requires adding <code>dir=\"rtl\"<\/code> to each <code>&lt;span&gt;<\/code> but also setting the column alignment for the whole table to <code>---:<\/code>. This will align all the text in the specified column, including the header. There seems to be no way to override the direction for text in individual cells.<\/p>\n<table>\n<thead>\n<tr>\n<th>Language<\/th>\n<th align=\"right\">Sample<\/th>\n<th>Feature setting<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>default<\/td>\n<td align=\"right\"><span dir=\"rtl\" class='scheherazadenew-R normal'>&#x062F;&#x0020;&#x0630;&#x0020;&#x0688;&#x0020;&#x0689;&#x0020;&#x068A;&#x0020;&#x068B;&#x0020;&#x068C;&#x0020;&#x068D;&#x0020;&#x068E;&#x0020;&#x068F;&#x0020;&#x0690;&#x0020;&#x06EE;&#x0020;&#x0759;&#x0020;&#x075A;&#x0020;&#x08AE;&#x0020;&#x0645;&#x0020;&#x0645;&#x0645;&#x0645;&#x0020;&#x0765;&#x0020;&#x0765;&#x0765;&#x0765;&#x0020;&#x0766;&#x0020;&#x0766;&#x0766;&#x0766;&#x0020; &#x08A7;&#x0020;&#x08A7;&#x08A7;&#x08A7;&#x0020; <\/br>&#x0647;&#x0020;&#x0647;&#x0647;&#x0647;&#x0020; &#x0626;&#x0020;&#x0626;&#x0626;&#x0626;&#x0020; &#x060C; &#x061B; &#x06F4; &#x06F6; &#x06F7; <\/br>&#x0628;&#x0651;&#x0650; &#x0628;&#x064F; &#x0628;&#x064C; &#x0628;&#x0657;<\/span><\/td>\n<td><\/td>\n<\/tr>\n<tr>\n<td>Sindhi<\/td>\n<td align=\"right\"><span dir=\"rtl\" class='scheherazadenew-R normal' lang='sd'>&#x062F;&#x0020;&#x0630;&#x0020;&#x0688;&#x0020;&#x0689;&#x0020;&#x068A;&#x0020;&#x068B;&#x0020;&#x068C;&#x0020;&#x068D;&#x0020;&#x068E;&#x0020;&#x068F;&#x0020;&#x0690;&#x0020;&#x06EE;&#x0020;&#x0759;&#x0020;&#x075A;&#x0020;&#x08AE;&#x0020;&#x0645;&#x0020;&#x0645;&#x0645;&#x0645;&#x0020;&#x0765;&#x0020;&#x0765;&#x0765;&#x0765;&#x0020;&#x0766;&#x0020;&#x0766;&#x0766;&#x0766;&#x0020; &#x08A7;&#x0020;&#x08A7;&#x08A7;&#x08A7;&#x0020; <\/br>&#x0647;&#x0020;&#x0647;&#x0647;&#x0647;&#x0020; &#x0626;&#x0020;&#x0626;&#x0626;&#x0626;&#x0020; &#x060C; &#x061B; &#x06F4; &#x06F6; &#x06F7; <\/br>&#x0628;&#x0651;&#x0650; &#x0628;&#x064F; &#x0628;&#x064C; &#x0628;&#x0657;<\/span><\/td>\n<td><code>lang=sd<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>Text examples are from the UDHR Article 26 (Arabic MSA). Additional useful information for handling bidirectional text is in two docs from the W3C: <a href=\"https:\/\/www.w3.org\/International\/questions\/qa-html-dir\" target=\"_blank\" rel=\"noopener\">Structural markup and right-to-left text in HTML<\/a> and <a href=\"https:\/\/www.w3.org\/International\/articles\/inline-bidi-markup\/\" target=\"_blank\" rel=\"noopener\">Inline markup and bidirectional text in HTML<\/a>.<\/p>\n<h2>Color<\/h2>\n<p>Text can be <span style=\"color:red;\">colored<\/span> by adding the CSS <em>style<\/em> property to the <code>&lt;span&gt;<\/code> of text.<\/p>\n<p>For some browsers (Firefox, Chrome) it also seems possible to color text without breaking the contextual text stream by adding a <code>&lt;span&gt;<\/code> within a <code>&lt;span&gt;<\/code>: <span dir=\"rtl\" class='scheherazadenew-R normal'>\u0646<span style=\"color:red;\">\u0646<\/span>\u0646<\/span>. <strong>However this does not seem to work in Safari and may not work in other environments. It also does not work in the PDF, so if you use this you may need to print the doc from Chrome to produce the PDF rather than using <em>makedocs<\/em> (which uses weasyprint).<\/strong><\/p>\n<h2>Horizontal rule<\/h2>\n<p>Paragraph before rule.<\/p>\n<hr \/>\n<p>Paragraph after rule.<\/p>\n<h2>Formatting using special html entities<\/h2>\n<p>H<sub>2<\/sub>O<\/p>\n<p>X<sup>n<\/sup> + Y<sup>n<\/sup> = Z<sup>n<\/sup><\/p>\n<p>Press <kbd>Ctrl<\/kbd>+<kbd>Shift<\/kbd>+<kbd>C<\/kbd> to copy.<\/p>\n<p>Text can be <mark>highlighted<\/mark>, though that can be very distracting.<\/p>\n<p><br \/>\n<\/p>\n<div class=\"footnotes\">\n<hr \/>\n<ol>\n<li id=\"fn-778-1\">\nHere is an example of how the footnote text is indicated. This example reference is in the text.&#160;<a href=\"#fnref-778-1\">&#8617;<\/a>\n<\/li>\n<li id=\"fn-778-anytext\">\nFootnote references can also be text but will still get numbered correctly. The references can be placed at the bottom of the markdown page.&#160;<a href=\"#fnref-778-anytext\">&#8617;<\/a>\n<\/li>\n<\/ol>\n<\/div>\n","protected":false},"excerpt":{"rendered":"<p>This document gives examples of how to use markdown for font documentation, for both in-project docs (html, pdf) and product site page source (md). Although these three target doc types each support some unique capabilities (e.g. product site accordions) this doc focuses on markdown that works for all three types. Paragraphs, text formatting, line breaking [&hellip;]<\/p>\n","protected":false},"author":2,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"_acf_changed":false,"hide_sidebar":false,"hide_h1":false,"footnotes":""},"class_list":["post-778","page","type-page","status-publish","hentry"],"acf":[],"_links":{"self":[{"href":"https:\/\/software.sil.org\/bjcree\/wp-json\/wp\/v2\/pages\/778","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/software.sil.org\/bjcree\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/software.sil.org\/bjcree\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/software.sil.org\/bjcree\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/software.sil.org\/bjcree\/wp-json\/wp\/v2\/comments?post=778"}],"version-history":[{"count":1,"href":"https:\/\/software.sil.org\/bjcree\/wp-json\/wp\/v2\/pages\/778\/revisions"}],"predecessor-version":[{"id":779,"href":"https:\/\/software.sil.org\/bjcree\/wp-json\/wp\/v2\/pages\/778\/revisions\/779"}],"wp:attachment":[{"href":"https:\/\/software.sil.org\/bjcree\/wp-json\/wp\/v2\/media?parent=778"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}