Improved Markdown documentation

Aperta
  • Qualcosa non va?
#23 0 commenti 2 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
35/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Stack tecnologico
markdown
Ambito
documentation

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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

Lingua principale
CSS
Stelle
22
Fork
79
Merge medio
2g 1h
PR unite (30g)
6

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di ExpressionEngine/ExpressionEngine-User-Guide

Tutte le issue di ExpressionEngine/ExpressionEngine-User-Guide

Issue simili

Altre issue su Documentation

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.