Programmatically access Markdown documentation.
توفر الواجهة البرمجة لدليل ماركداون مجموعة فرعية من توثيقات دليل ماركداون بتنسيق JSON. نأمل أن يستخدم مطورو البرمجيات والمؤسسات هذه الواجهة البرمجية لاستهلاك توثيقنا البرمجي وعرضها في التطبيقات وعلى مواقع الويب.
لماذا إنشاء واجهة برمجية لتوثيقات ماركداون؟ بسبب وجود الكثير من توثيقات ماركداون المتكررة على الويب! يبدو أن كل شخص لديه نسخته الخاصة من توثيقات ماركداون لتطبيقه أو موقعه على الويب. هذا مؤسف لأن معظمه متماثل تمامًا.
ثم جاءت اللحظة الموعودة. 💡أدركنا أنه يمكننا إنشاء واجهة برمجية تستخدم JSON باستخدام التوثيق من دليل ماركداون. بهذه الطريقة، يمكن لمطوري البرمجيات البدء في استخدام الواجهة البرمجية لتضمين توثيقاتنا في تطبيقاتهم، ويمكن للمؤسسات مثل الجامعات والمكتبات استخدام هذه الواجهة البرمجية لتضمين توثيقاتنا على مواقعهم على الويب.
نود أن نرى أن دليل ماركداون أصبح مستودع التوثيقات المركزي لآلاف تعليمات ماركداون المنتشرة في جميع أنحاء الإنترنت. هل ستعمل؟ لا أحد يعرف ذلك يقينًا! هناك شيء واحد مؤكد على الرغم من ذلك: لا يمكننا الانتظار لمعرفة ما ستفعله به. 🤘
صُمّمت الواجهة البرمجية لدليل ماركداون لتوفير توثيقات ماركداون الأساسية فقط. نتيجة لذلك، لا تتضمن الواجهة البرمجية جميع التوثيقات المتاحة على موقع دليل ماركداون. مثلًا، لا يتوفر قسم إضافة العناصر للقوائم من خلال نقطة وصول القواعد الأساسية.
تحتوي نقطة وصول القواعد الأساسية على توثيق عناصر ماركداون الموضحة في مستند تصميم جون جروبر (John Gruber) والموضّحة في صفحة القواعد الأساسية.
curl https://www.guide.dawin.io/api/v1/basic-syntax.json
| { | |
| "status": "OK", | |
| "last_updated": "2017-11-04", | |
| "basic_syntax": [ | |
| { | |
| "name" : "Blockquotes", | |
| "description" : "To create a blockquote, add a `>` in front of a paragraph.", | |
| "examples" : [ | |
| { | |
| "markdown" : "> Dorothy followed her through many of the beautiful rooms in her castle.", | |
| "html" : "<blockquote><p>Dorothy followed her through many of the beautiful rooms in her castle.</p></blockquote>" | |
| } | |
| ], | |
| "additional_examples" : [ | |
| { | |
| "name" : "Blockquotes with Multiple Paragraphs", | |
| "description" : "Blockquotes can contain multiple paragraphs. Add a `>` on the blank lines between the paragraphs.", | |
| "markdown" : "> Dorothy followed her through many of the beautiful rooms in her castle.\n>\n> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.\n", | |
| "html" : "<blockquote><p>Dorothy followed her through many of the beautiful rooms in her castle.</p><p>The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.</p></blockquote>" | |
| } , | |
| { | |
| "name" : "Nested Blockquotes", | |
| "description" : "Blockquotes can be nested. Add a `>>` in front of the paragraph you want to nest.", | |
| "markdown" : "> Dorothy followed her through many of the beautiful rooms in her castle.\n>\n>> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.\n", | |
| "html" : "<blockquote><p>Dorothy followed her through many of the beautiful rooms in her castle.</p><blockquote><p>The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.</p></blockquote></blockquote>" | |
| } , | |
| { | |
| "name" : "Blockquotes with Other Elements", | |
| "description" : "Blockquotes can contain other Markdown formatted elements. Not all elements can be used — you'll need to experiment to see which ones work.", | |
| "markdown" : "> ### The quarterly results look great!\n>\n> - Revenue was off the chart.\n> - Profits were higher than ever.\n>\n> *Everything* is going according to **plan**.\n", | |
| "html" : "<blockquote><h3>The quarterly results look great!</h3><ul><li>Revenue was off the chart.</li><li>Profits were higher than ever.</li></ul><p><em>Everything</em> is going according to <strong>plan</strong>.</p></blockquote>" | |
| } | |
| ] | |
| } , | |
| { | |
| "name" : "Bold", | |
| "description" : "To bold text, add two asterisks or underscores before and after a word or phrase. To bold the middle of a word for emphasis, add two asterisks without spaces around the letters.", | |
| "examples" : [ | |
| { | |
| "markdown" : "I just love **bold text**.", | |
| "html" : "I just love <strong>bold text</strong>." | |
| } , | |
| { | |
| "markdown" : "I just love __bold text__.", | |
| "html" : "I just love <strong>bold text</strong>." | |
| } , | |
| { | |
| "markdown" : "Love**is**bold", | |
| "html" : "Love<strong>is</strong>bold" | |
| } | |
| ], | |
| "additional_examples" : [ | |
| ] | |
| } , | |
| { | |
| "name" : "Code", | |
| "description" : "To denote a word or phrase as code, enclose it in tick marks (`` ` ``).", | |
| "examples" : [ | |
| { | |
| "markdown" : "At the command prompt, type `nano`.", | |
| "html" : "At the command prompt, type <code>nano</code>." | |
| } | |
| ], | |
| "additional_examples" : [ | |
| { | |
| "name" : "Escaping Tick Marks", | |
| "description" : "If the word or phrase you want to denote as code includes one or more tick marks, you can escape it by enclosing the word or phrase in double tick marks (<code>``</code>).", | |
| "markdown" : "``Use `code` in your Markdown file.``", | |
| "html" : "<code>Use `code` in your Markdown file.</code>" | |
| } , | |
| { | |
| "name" : "Code Blocks", | |
| "description" : "To create code blocks, indent every line of the block by at least four spaces or one tab.", | |
| "markdown" : "<html>\n <head>\n </head>\n</html>\n", | |
| "html" : "<pre><code><html><head></head></html></code></pre>" | |
| } | |
| ] | |
| } , | |
| { | |
| "name" : "Headings", | |
| "description" : "To create a heading, add number signs (`#`) in front of a word or phrase. The number of number signs you use should correspond to the heading level. For example, to create a heading level three (`<h3>`), use three number signs (e.g., `### My Header`).", | |
| "examples" : [ | |
| { | |
| "markdown" : "# Heading level 1", | |
| "html" : "<h1>Heading level 1</h1>" | |
| } , | |
| { | |
| "markdown" : "## Heading level 2", | |
| "html" : "<h2>Heading level 2</h2>" | |
| } , | |
| { | |
| "markdown" : "### Heading level 3", | |
| "html" : "<h3>Heading level 3</h3>" | |
| } , | |
| { | |
| "markdown" : "#### Heading level 4", | |
| "html" : "<h4>Heading level 4</h4>" | |
| } , | |
| { | |
| "markdown" : "##### Heading level 5", | |
| "html" : "<h5>Heading level 5</h5>" | |
| } , | |
| { | |
| "markdown" : "###### Heading level 6", | |
| "html" : "<h6>Heading level 6</h6>" | |
| } | |
| ], | |
| "additional_examples" : [ | |
| { | |
| "name" : "Alternative H1 Syntax", | |
| "description" : "Alternatively, on the line below the text, add any number of == characters for heading level 1.", | |
| "markdown" : "Heading level 1\n===============\n", | |
| "html" : "<h1>Heading level 1</h1>" | |
| } , | |
| { | |
| "name" : "Alternative H2 Syntax", | |
| "description" : "Alternatively, on the line below the text, add any number of -- characters for heading level 2.", | |
| "markdown" : "Heading level 2\n---------------\n", | |
| "html" : "<h2>Heading level 2</h2>" | |
| } | |
| ] | |
| } , | |
| { | |
| "name" : "Horizontal Rules", | |
| "description" : "To create a horizontal rule, use three or more asterisks (`***`), dashes (`---`), or underscores (`___`) on a line by themselves.", | |
| "examples" : [ | |
| { | |
| "markdown" : "***", | |
| "html" : "<hr>" | |
| } , | |
| { | |
| "markdown" : "---", | |
| "html" : "<hr>" | |
| } , | |
| { | |
| "markdown" : "_________________", | |
| "html" : "<hr>" | |
| } | |
| ], | |
| "additional_examples" : [ | |
| ] | |
| } , | |
| { | |
| "name" : "Images", | |
| "description" : "To add an image, add an exclamation mark (`!`), followed by alt text in brackets, and the path or URL to the image asset in parentheses. You can optionally add a title after the URL in the parentheses.", | |
| "examples" : [ | |
| { | |
| "markdown" : "![Philadelphia's Magic Gardens. This place was so cool!](/assets/images/philly-magic-gardens.jpg \"Philadelphia's Magic Gardens\")\n", | |
| "html" : "<img src=\"/assets/images/philly-magic-garden.jpg\" class=\"img-responsive\" alt=\"Philadelphia's Magic Gardens. This place was so cool!\" title=\"Philadelphia's Magic Gardens\">" | |
| } | |
| ], | |
| "additional_examples" : [ | |
| { | |
| "name" : "Linking Images", | |
| "description" : "To add a link to an image, enclose the Markdown for the image in brackets, and then add the link in parentheses.", | |
| "markdown" : "[![An old rock in the desert](/assets/images/shiprock.jpg \"Shiprock, New Mexico by Beau Rogers\")](https://www.flickr.com/photos/beaurogers/31833779864/in/photolist-Qv3rFw-34mt9F-a9Cmfy-5Ha3Zi-9msKdv-o3hgjr-hWpUte-4WMsJ1-KUQ8N-deshUb-vssBD-6CQci6-8AFCiD-zsJWT-nNfsgB-dPDwZJ-bn9JGn-5HtSXY-6CUhAL-a4UTXB-ugPum-KUPSo-fBLNm-6CUmpy-4WMsc9-8a7D3T-83KJev-6CQ2bK-nNusHJ-a78rQH-nw3NvT-7aq2qf-8wwBso-3nNceh-ugSKP-4mh4kh-bbeeqH-a7biME-q3PtTf-brFpgb-cg38zw-bXMZc-nJPELD-f58Lmo-bXMYG-bz8AAi-bxNtNT-bXMYi-bXMY6-bXMYv)\n", | |
| "html" : "<a href=\"https://www.flickr.com/photos/beaurogers/31833779864/in/photolist-Qv3rFw-34mt9F-a9Cmfy-5Ha3Zi-9msKdv-o3hgjr-hWpUte-4WMsJ1-KUQ8N-deshUb-vssBD-6CQci6-8AFCiD-zsJWT-nNfsgB-dPDwZJ-bn9JGn-5HtSXY-6CUhAL-a4UTXB-ugPum-KUPSo-fBLNm-6CUmpy-4WMsc9-8a7D3T-83KJev-6CQ2bK-nNusHJ-a78rQH-nw3NvT-7aq2qf-8wwBso-3nNceh-ugSKP-4mh4kh-bbeeqH-a7biME-q3PtTf-brFpgb-cg38zw-bXMZc-nJPELD-f58Lmo-bXMYG-bz8AAi-bxNtNT-bXMYi-bXMY6-bXMYv\"><img src=\"/assets/images/shiprock.jpg\" alt=\"An old rock in the desert\" title=\"Shiprock, New Mexico by Beau Rogers\"></a>" | |
| } | |
| ] | |
| } , | |
| { | |
| "name" : "Italic", | |
| "description" : "To italicize text, add one asterisk or underscore before and after a word or phrase. To italicize the middle of a word for emphasis, add one asterisk without spaces around the letters.", | |
| "examples" : [ | |
| { | |
| "markdown" : "Italicized text is the *cat's meow*.", | |
| "html" : "Italicized text is the <em>cat's meow</em>." | |
| } , | |
| { | |
| "markdown" : "Italicized text is the _cat's meow_.", | |
| "html" : "Italicized text is the <em>cat's meow</em>." | |
| } , | |
| { | |
| "markdown" : "A*cat*meow", | |
| "html" : "A<em>cat</em>meow" | |
| } | |
| ], | |
| "additional_examples" : [ | |
| ] | |
| } , | |
| { | |
| "name" : "Line Breaks", | |
| "description" : "To create a line break (`<br>`), end a line with two or more spaces, and then type return.", | |
| "examples" : [ | |
| { | |
| "markdown" : "This is the first line. \nAnd this is the second line.\n", | |
| "html" : "<p>This is the first line. <br>And this is the second line.</p>" | |
| } | |
| ], | |
| "additional_examples" : [ | |
| ] | |
| } , | |
| { | |
| "name" : "Links", | |
| "description" : "To create a link, enclose the link text in brackets (e.g., `[Duck Duck Go]`) and then follow it immediately with the URL in parentheses (e.g., `(https://duckduckgo.com)`). You can optionally add a title after the URL in the parentheses.", | |
| "examples" : [ | |
| { | |
| "markdown" : "My favorite search engine is [Duck Duck Go](https://duckduckgo.com \"The best search engine for privacy\").", | |
| "html" : "My favorite search engine is <a href=\"https://duckduckgo.com\" title=\"The best search engine for privacy\">Duck Duck Go</a>." | |
| } | |
| ], | |
| "additional_examples" : [ | |
| { | |
| "name" : "URLs and Email Addresses", | |
| "description" : "To quickly turn a URL or email address into a link, enclose it in angle brackets.", | |
| "markdown" : "<https://www.markdownguide.org><fake@example.com>", | |
| "html" : "<a href=\"https://www.markdownguide.org\">https://www.markdownguide.org</a><a href=\"mailto:fake@example.com\">fake@example.com</a>" | |
| } , | |
| { | |
| "name" : "Formatting Links", | |
| "description" : "To emphasize links, add asterisks before and after the brackets and parentheses.", | |
| "markdown" : "I love supporting **[EFF](https://eff.org)**. This is the *[Markdown Guide](https://www.markdownguide.org)*.", | |
| "html" : "I love supporting <strong><a href=\"https://eff.org\">EFF</a></strong>. This is the <em><a href=\"https://www.markdownguide.org\">Markdown Guide</a></em>." | |
| } | |
| ] | |
| } , | |
| { | |
| "name" : "Ordered Lists", | |
| "description" : "To create an ordered list, add line items with numbers followed by periods. The numbers don't have to be in numerical order, but the list should start with the number one.", | |
| "examples" : [ | |
| { | |
| "markdown" : "1. First item\n2. Second item\n3. Third item\n4. Fourth item\n", | |
| "html" : "<ol><li>First item</li><li>Second item</li><li>Third item</li><li>Fourth item</li></ol>" | |
| } , | |
| { | |
| "markdown" : "1. First item\n1. Second item\n1. Third item\n1. Fourth item\n", | |
| "html" : "<ol><li>First item</li><li>Second item</li><li>Third item</li><li>Fourth item</li></ol>" | |
| } , | |
| { | |
| "markdown" : "1. First item\n8. Second item\n3. Third item\n5. Fourth item\n", | |
| "html" : "<ol><li>First item</li><li>Second item</li><li>Third item</li><li>Fourth item</li></ol>" | |
| } , | |
| { | |
| "markdown" : "1. First item\n2. Second item\n3. Third item\n 1. Indented item\n 2. Indented item\n4. Fourth item\n", | |
| "html" : "<ol><li>First item</li><li>Second item</li><li>Third item<ol><li>Indented item</li><li>Indented item</li></ol></li><li>Fourth item</li></ol>" | |
| } | |
| ], | |
| "additional_examples" : [ | |
| ] | |
| } , | |
| { | |
| "name" : "Paragraphs", | |
| "description" : "To create paragraphs, use a blank line to separate one or more lines of text. You should not indent paragraphs with spaces or tabs.", | |
| "examples" : [ | |
| { | |
| "markdown" : "I really like using Markdown.\n\nI think I'll use it to format all of my documents from now on.\n", | |
| "html" : "<p>I really like using Markdown.</p><p>I think I'll use it to format all of my documents from now on.</p>" | |
| } | |
| ], | |
| "additional_examples" : [ | |
| ] | |
| } , | |
| { | |
| "name" : "Unordered Lists", | |
| "description" : "To create an unordered list, add dashes (`-`), asterisks (`*`), or plus signs (`+`) in front of line items. Indent one or more items to create a nested list.", | |
| "examples" : [ | |
| { | |
| "markdown" : "- First item\n- Second item\n- Third item\n- Fourth item\n", | |
| "html" : "<ul><li>First item</li><li>Second item</li><li>Third item</li><li>Fourth item</li></ul>" | |
| } , | |
| { | |
| "markdown" : "* First item\n* Second item\n* Third item\n* Fourth item\n", | |
| "html" : "<ul><li>First item</li><li>Second item</li><li>Third item</li><li>Fourth item</li></ul>" | |
| } , | |
| { | |
| "markdown" : "+ First item\n* Second item\n- Third item\n+ Fourth item\n", | |
| "html" : "<ul><li>First item</li><li>Second item</li><li>Third item</li><li>Fourth item</li></ul>" | |
| } , | |
| { | |
| "markdown" : "- First item\n- Second item\n- Third item\n - Indented item\n - Indented item\n- Fourth item\n", | |
| "html" : "<ul><li>First item</li><li>Second item</li><li>Third item<ul><li>Indented item</li><li>Indented item</li></ul></li><li>Fourth item</li></ul>" | |
| } | |
| ], | |
| "additional_examples" : [ | |
| ] | |
| } | |
| ] | |
| } |
توفر نقطة الوصول للملّخص المرجعي نظرة عامة على عناصر ماركداون الأساسية والموسّعة الأكثر شيوعًا، كما هو موضح في صفحة الملخص المرجعي.
curl https://www.guide.dawin.io/api/v1/cheat-sheet.json
| { | |
| "status": "OK", | |
| "last_updated": "2017-11-10", | |
| "cheat_sheet": [ | |
| { | |
| "basic_syntax": [ | |
| { | |
| "element" : "Blockquotes", | |
| "syntax" : "> blockquote" | |
| } , | |
| { | |
| "element" : "Bold", | |
| "syntax" : "**bold text**" | |
| } , | |
| { | |
| "element" : "Code", | |
| "syntax" : "`code`" | |
| } , | |
| { | |
| "element" : "Headings", | |
| "syntax" : "# H1\n## H2\n### H3\n" | |
| } , | |
| { | |
| "element" : "Horizontal Rules", | |
| "syntax" : "---" | |
| } , | |
| { | |
| "element" : "Images", | |
| "syntax" : "" | |
| } , | |
| { | |
| "element" : "Italic", | |
| "syntax" : "*italicized text*" | |
| } , | |
| { | |
| "element" : "Links", | |
| "syntax" : "[title](https://www.example.com)" | |
| } , | |
| { | |
| "element" : "Ordered Lists", | |
| "syntax" : "1. First item\n2. Second item\n3. Third item\n" | |
| } , | |
| { | |
| "element" : "Unordered Lists", | |
| "syntax" : "- First item\n- Second item\n- Third item\n" | |
| } | |
| ] | |
| }, | |
| { | |
| "extended_syntax": [ | |
| { | |
| "element" : "Definition Lists", | |
| "syntax" : "term\n: definition\n" | |
| } , | |
| { | |
| "element" : "Fenced Code Blocks", | |
| "syntax" : "```\n{\n\"firstName\": \"John\",\n\"lastName\": \"Smith\",\n\"age\": 25\n}\n```\n" | |
| } , | |
| { | |
| "element" : "Footnotes", | |
| "syntax" : "Here's a sentence with a footnote. [^1]\n\n[^1]: This is the footnote.\n" | |
| } , | |
| { | |
| "element" : "Heading IDs", | |
| "syntax" : "### My Great Heading {#custom-id}" | |
| } , | |
| { | |
| "element" : "Strikethrough", | |
| "syntax" : "~~The world is flat.~~" | |
| } , | |
| { | |
| "element" : "Tables", | |
| "syntax" : "| Syntax | Description |\n| ----------- | ----------- |\n| Header | Title |\n| Paragraph | Text |\n" | |
| } , | |
| { | |
| "element" : "Task Lists", | |
| "syntax" : "- [x] Write the press release\n- [ ] Update the website\n- [ ] Contact the media\n" | |
| } | |
| ] | |
| } | |
| ] | |
| } |
فيما يلي قائمة بجميع التغييرات التي أجريت على الواجهة البرمجية لدليل ماركداون.
2018-10-18
- حُدّثت نقطة الوصول للملخص المرجعي لتضمين معلومات حول قوائم التعريف (<dl>)
2018-07-12
- تحديث وصف الروابط لتضمين معلومات حول إضافة العناوين (titles) في وسم الروابط
2017-11-10
- إضافة نقطة وصول الملخص المرجعي
2017-11-04
لا تتوقف الآن! 🚀 قم بتمييز مستودع GitHub بنجمة ثم أدخل عنوان بريدك الإلكتروني أدناه لتلقي دروس Markdown التعليمية الجديدة عبر البريد الإلكتروني. نحن لا نرسل بريدا مزعجا!