Improved Markdown documentation

未關閉
  • 哪裡不對？
#23 0 則留言 2 個 reaction 已指派 0 人 在 GitHub 檢視

還沒有人認領這個 Issue。

評估

難度
3/5
預估耗時
1-2 天
新手友好度
35/100
Issue 類型
文件
描述清晰度
基本清楚
活躍度
停滯
技術堆疊
markdown
領域
documentation

研究方向

Start with the Markdown section of the text formatting page linked in the issue, then compare its references to the Gruber guide, Markdown Extra, and Smartypants documentation. Document EE’s supported syntax and implementation quirks in one definitive page, link to it from the text formatting page, and make clear which Smartypants transformations apply.

由索引模型根據 Issue 內容生成。

描述

good first issue

Suggested Change
Comprehensive, all-in-one-place documentation for EE's specific implementation of Markdown.

Reasoning
Currently the documentation for anyone who wants to use Markdown in EE is scattered across three (arguably four) locations: John Gruber's original guide; the Markdown Extra page which consists of a list of ways in which the implementation is different to the Gruber original (ie. it notes the differences that sit atop the base rules but doesn't repeat the original guide, so a user really needs to refer to both simultaneously); and lastly the Smartypants page which lists further text transformations that sit on top of the other two guides. Additionally there is the EE documentation that links to those three pages but also makes note of specific Smartypants text transforms — which creates some ambiguity regarding whether or not the EE Smartypants parser performs all the transforms noted in the 3rd party page, or whether it is a cut-down version that only makes those changes called out in the EE docs (smart quotes, en dashes, em dashes, & ellipses).

This leaves us with 4 sources of cascading information, each one amending or overruling the previous one (or introducing mild ambiguity) — and after all that we are still left with aspects of Markdown implementation that behave differently to ALL of those sources combined. (An example: standard Markdown syntax states that a <br> can be added inside a paragraph by typing two spaces followed by the word return and then a single carriage return. The EE implementation, however, requires only the two spaces followed by a carriage return. Adding the word return in the middle in fact prevents the line break from being inserted).

It would, therefore, be extremely helpful if there could be a single, definitive documentation source for EE's Markdown implementation — ideally, a page in the docs (and linked to from the Markdown section of the text formatting page) that distils the documentation from the various 3rd party sources into a single, rational whole, which removes any standard Markdown syntax rules that do not apply to EE's library, and which also documents any additional quirks specific to the EE implementation.

Additional context
None

主要語言
CSS
星號
22
分支
79
平均合併
2 天 1 小時
30 天內合併 PR
6

環境準備

從這裡開始

  1. 先讀完整個 Issue，再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫，在一個分支上完成修改。
  4. 送出 Pull Request，並在描述裡引用這個 Issue 編號。

ExpressionEngine/ExpressionEngine-User-Guide 的其他 Issue

查看 ExpressionEngine/ExpressionEngine-User-Guide 的全部 Issue

相似的 Issue

更多 Documentation Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。