Improved Markdown documentation

Abierto
  • ¿Algo no está bien?
#23 0 comentarios 2 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
35/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
markdown
Área
documentation

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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

Lenguaje dominante
CSS
Estrellas
22
Forks
79
Merge medio
2 d 1 h
PR fusionados (30 d)
6

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de ExpressionEngine/ExpressionEngine-User-Guide

Todos los issues de ExpressionEngine/ExpressionEngine-User-Guide

Issues similares

Más issues de Documentation

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.