Improved Markdown documentation

Ouverte
  • Quelque chose ne va pas ?
#23 0 commentaires 2 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

Évaluation

Difficulté
3/5
Temps estimé
1-2 jours
Accessibilité débutants
35/100
Type d'issue
Documentation
Clarté
Plutôt claire
Activité
À l'abandon
Stack technique
markdown
Domaine
documentation

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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

Langage dominant
CSS
Étoiles
22
Forks
79
Merge moyen
2 j 1 h
PR mergées (30 j)
6

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de ExpressionEngine/ExpressionEngine-User-Guide

Toutes les issues de ExpressionEngine/ExpressionEngine-User-Guide

Issues similaires

Plus d'issues Documentation

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.