Redcarpet está escrito con azúcar, especias y todo lo bueno.

Estado de construcción
Ayuda a contribuir al código abierto
Versión de gema

Redcarpet es una biblioteca de Ruby para el procesamiento de Markdown que huele a mariposas y palomitas de maíz.

Esta biblioteca está escrita por personas.

Redcarpet fue escrita por Vicent Martí. Es mantenido por Robin Dupret y Matt Rogers.

Redcarpet no sería posible sin la biblioteca Sundown y sus autores (Natacha Porté, Vicent Martí y sus muchos colaboradores increíbles).

Puedes instalarlo totalmente como una gema.

Redcarpet está fácilmente disponible como una gema Ruby. Construirá algunas extensiones nativas, pero el analizador es independiente y no requiere bibliotecas instaladas. A partir de Redcarpet 3.0, la versión mínima requerida de Ruby es 1.9.2 (o Rubinius en modo 1.9).

$ [sudo] gem install redcarpet

Si necesita usarlo con Ruby 1.8.7, tendrá que quedarse con 2.3.0:

$ [sudo] gem install redcarpet -v 2.3.0

La fuente de Redcarpet está disponible en GitHub:

$ git clone git://github.com/vmg/redcarpet.git

y es como De Verdad fácil de usar

El núcleo de la biblioteca Redcarpet es el Redcarpet::Markdown clase. Cada instancia de la clase se adjunta a un Renderer objeto; la clase Markdown realiza el análisis de un documento y utiliza el representador adjunto para generar la salida.

los Redcarpet::Markdown Se recomienda crear una instancia del objeto una vez con la configuración requerida y reutilizarlo entre análisis.

# Initializes a Markdown parser
markdown = Redcarpet::Markdown.new(renderer, extensions = {})

Aquí el renderer variable se refiere a un objeto renderizador, que hereda de Redcarpet::Render::Base. Si el objeto dado no ha sido instanciado, la biblioteca lo hará con argumentos predeterminados.

Renderizado con el Markdown el objeto se hace a través de Markdown#render. A diferencia de la API de RedCloth, el texto a representar se pasa como un argumento y no se almacena dentro del Markdown ejemplo, para fomentar la reutilización. Ejemplo:

markdown.render("This is *bongos*, indeed.")
# => "<p>This is <em>bongos</em>, indeed.</p>"

También puede especificar un hash que contenga las extensiones Markdown que identificará el analizador. Se aceptan las siguientes prórrogas:

:no_intra_emphasis: no analice el énfasis dentro de las palabras. cadenas como foo_bar_baz no generará <em> etiquetas
:tables: tablas de análisis, estilo PHP-Markdown.
:fenced_code_blocks: analizar bloques de código delimitado, estilo PHP-Markdown. Bloques delimitados con 3 o más ~ o los acentos graves se considerarán como código, sin necesidad de sangría. Se puede agregar un nombre de idioma opcional al final de la cerca de apertura para el bloque de código.
:autolink: analizar enlaces incluso cuando no están encerrados en <>
caracteres. Los enlaces automáticos para los protocolos http, https y ftp se detectarán automáticamente. Direcciones de correo electrónico y enlaces http sin protocolo, pero empezando por www también se manejan.
:disable_indented_code_blocks: no analice los bloques de código de descuento habituales. Markdown convierte texto con cuatro espacios al frente de cada línea en bloques de código. Esta opción le impide hacerlo. Recomendado para usar con fenced_code_blocks: true.
:strikethrough: análisis tachado, estilo PHP-Markdown. Dos ~ los caracteres marcan el inicio de un tachado, p. ej. this is ~~good~~ bad.
:lax_spacing: Los bloques HTML no requieren estar rodeados por una línea vacía como en el estándar Markdown.
:space_after_headers: siempre se requiere un espacio entre el hash al comienzo de un encabezado y su nombre, por ejemplo #this is my header
no sería un encabezado válido.
:superscript: analizar superíndices después de la ^ personaje; los superíndices contiguos se anidan juntos, y los valores complejos se pueden encerrar entre paréntesis, por ejemplo
this is the 2^(nd) time.
:underline: analiza el énfasis subrayado como subrayado.
This is _underlined_ but this is still *italic*.
:highlight: analizar los aspectos más destacados.
This is ==highlighted==. Se parece a esto: <mark>highlighted</mark>
:quote: analizar citas.
This is a "quote". Se parece a esto: <q>quote</q>
:footnotes: analizar notas al pie, estilo PHP-Markdown. Una nota al pie funciona de manera muy similar a un enlace de estilo de referencia: consta de un marcador al lado del texto (p. ej.
This is a sentence.[^1]) y una definición de nota al pie en su propia línea en cualquier parte del documento (p. ej. [^1]: This is a footnote.).

Ejemplo:

markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML, autolink: true, tables: true)

Cariño, te preparé un par de renderizadores para el almuerzo.

Redcarpet viene con dos renderizadores incorporados, Redcarpet::Render::HTML y
Redcarpet::Render::XHTML, que generan HTML y XHTML, respectivamente. Estos renderizadores están realmente implementados en C y, por lo tanto, ofrecen un rendimiento brillante, varios grados de magnitud más rápidos que otras soluciones de Ruby Markdown.

Todas las marcas de representación que anteriormente se aplicaban solo a la salida HTML ahora se han movido a la Redcarpet::Render::HTML clase, y puede habilitarse al instanciar el renderizador:

Redcarpet::Render::HTML.new(render_options = {})

Inicializa un renderizador HTML. Están disponibles las siguientes banderas:

:filter_html: no permite ningún HTML ingresado por el usuario en la salida.
:no_images: no generar ninguna <img> etiquetas
:no_links: no generar ninguna <a> etiquetas
:no_styles: no generar ninguna <style> etiquetas
:escape_html: escapar de cualquier etiqueta HTML. Esta opción tiene prioridad sobre
:no_styles, :no_links, :no_images y :filter_html lo que significa que cualquier etiqueta existente se escapará en lugar de eliminarse.
:safe_links_only: solo genera enlaces para protocolos que se consideran seguros.
:with_toc_data: agregue anclajes HTML a cada encabezado en el HTML de salida, para permitir el enlace a cada sección.
:hard_wrap: insertar HTML <br> etiquetas dentro de párrafos donde el documento Markdown original tenía líneas nuevas (de forma predeterminada, Markdown ignora estas líneas nuevas).
:xhtml: etiquetas de salida compatibles con XHTML. Esta opción siempre está habilitada en el
Render::XHTML renderizador
:prettify: añadir clases de prettyprint a <code> etiquetas para google-code-prettify.
:link_attributes: hash de atributos adicionales para agregar a los enlaces.

Ejemplo:

renderer = Redcarpet::Render::HTML.new(no_links: true, hard_wrap: true)

los HTML renderer tiene una versión alternativa, Redcarpet::Render::HTML_TOCque generará una tabla de contenido en HTML basada en los encabezados del documento Markdown.

Al crear una instancia de este objeto de renderizado, opcionalmente puede pasar un nesting_level
opción que toma un número entero o un rango y le permite hacer que represente solo encabezados en ciertos niveles.

Redcarpet también incluye un renderizador de texto sin formato, Redcarpet::Render::StripDownque elimina todo el formato:

require 'redcarpet'
require 'redcarpet/render_strip'

markdown = Redcarpet::Markdown.new(Redcarpet::Render::StripDown)

markdown.render("**This** _is_ an [example](http://example.org/).")
# => "This is an example (http://example.org/)."

E incluso puedes cocinar tu propia

Los renderizadores personalizados se crean heredándolos de un renderizador existente. Los renderizadores incorporados, HTML y XHTML puede extenderse como tal:

# Create a custom renderer that sets a custom class for block-quotes.
class CustomRender < Redcarpet::Render::HTML
  def block_quote(quote)
    %(<blockquote class="my-custom-class">#{quote}</blockquote>)
  end
end

markdown = Redcarpet::Markdown.new(CustomRender, fenced_code_blocks: true)

Pero también se pueden crear nuevos renderizadores desde cero extendiendo la clase base abstracta Redcarpet::Render::Base (ver lib/redcarpet/render_man.rb para una implementación de ejemplo de un renderizador de página de manual):

class ManPage < Redcarpet::Render::Base
  # you get the drill -- keep going from here
end

El renderizador puede implementar los siguientes métodos de instancia:

Llamadas a nivel de bloque

Si el valor de retorno del método es nil, el bloque será saltado. Por lo tanto, asegúrese de que su renderizador tenga al menos un paragraph método implementado. Si no se implementa el método para un elemento de documento, se omitirá el bloque.

Ejemplo:

class RenderWithoutCode < Redcarpet::Render::HTML
  def block_code(code, language)
    nil
  end
end

block_code(código, idioma)
block_quote(cita)
bloque_html(sin procesar_html)
notas al pie (contenido)
footnote_def(contenido, número)
encabezado (texto, nivel de encabezado)
hrule()
list(contenido, list_type)
list_item(texto, list_type)
texto de párrafo)
tabla (encabezado, cuerpo)
tabla_fila(contenido)
table_cell(contenido, alineación, encabezado)

Llamadas de nivel de tramo

Un valor de retorno de nil no generará ningún dato. Si no se implementa el método para un elemento de documento, el contenido del tramo se copiará palabra por palabra:

autoenlace(enlace, tipo_enlace)
intervalo de códigos (código)
doble_énfasis(texto)
énfasis (texto)
imagen (enlace, título, alt_text)
salto de línea()
enlace (enlace, título, contenido)
sin procesar_html(sin procesar_html)
triple_énfasis(texto)
tachado (texto)
superíndice (texto)
subrayar (texto)
Subrayar el texto)
cita (texto)
footnote_ref(número)

Nota: Al anular el método de un renderizador, asegúrese de devolver un elemento HTML con un nivel que coincida con el nivel de ese método (por ejemplo, devolver un elemento de bloque al anular una devolución de llamada a nivel de bloque). De lo contrario, la salida puede ser inesperada.

Representación de bajo nivel

entidad (texto)
texto_normal(texto)

Encabezado del documento

Renderizado antes que cualquier otro elemento:

doc_header()

Pie de página del documento

Representado después de todos los demás elementos:

doc_footer()

Pre/post-proceso

Devolución de llamada especial: preprocesar o posprocesar todo el documento antes o después de que comience el proceso de renderizado:

preprocesar (documento_completo)
postproceso(documento_completo)

Puede consultar “¿Cómo ampliar la biblioteca Markdown de Redcarpet 2?” para algunas explicaciones más.

Además, ahora nuestros pantalones son mucho más inteligentes.

Redcarpet 2 viene con una implementación independiente de SmartyPants. Es totalmente compatible con la implementación original. Es el analizador de SmartyPants más rápido que existe, con una diferencia de varios órdenes de magnitud.

El analizador SmartyPants se puede encontrar en Redcarpet::Render::SmartyPants. Se ha implementado como un módulo, por lo que se puede utilizar de forma independiente o como complemento.

Cuando se mezcla con una clase Renderer, anulará la postprocess método para realizar reemplazos de SmartyPants una vez que se completa el renderizado.

# Mixin
class HTMLWithPants < Redcarpet::Render::HTML
  include Redcarpet::Render::SmartyPants
end

# Standalone
Redcarpet::Render::SmartyPants.render("<p>Oh SmartyPants, you're so crazy...</p>")

SmartyPants funciona sobre el HTML ya renderizado e ignorará los reemplazos dentro del contenido de las etiquetas HTML y dentro de bloques HTML específicos como
<code> o <pre>.

¿Qué? ¿Realmente quieres mezclar renderizadores Markdown?

Redcarpet solía ser un reemplazo directo de Redcloth. Este ya no es el caso desde la versión 2: ahora tiene su propia API, pero conserva el nombre anterior. Sí, eso significa que Redcarpet no es retrocompatible con las versiones 1.X.

Cada renderizador tiene su propia API y su propio conjunto de extensiones: debe elegir una (no tiene que ser Redcarpet, ¡aunque sería genial!), escribir su software en consecuencia y obligar a sus usuarios a instalarlo. Esa es la única forma de tener una salida Markdown confiable y predecible en su programa.

Markdown ya está lo suficientemente mal especificado; si crea un software que es independiente del renderizador, ¡los resultados serán completamente poco confiables!

Aún así, si fuerzas importantes (digamos, tornados u otros desastres naturales) lo obligan a mantener una capa compatible con Markdown, Redcarpet también es compatible con esto:

require 'redcarpet/compat'

Requerir la biblioteca de compatibilidad declarará un Markdown clase con la API clásica de RedCloth, por ejemplo

Markdown.new('this is my text').to_html

Esta clase hace que Markdown cumpla con los estándares al 100 % con 0 extensiones. Nada. Ni siquiera intentes habilitar extensiones con una capa de compatibilidad, porque eso es una pesadilla de mantenimiento y no funcionará.

En un tema relacionado: si su gema Markdown tiene un lib/markdown.rb archivo que monkeypatches la clase Markdown, eres un ser humano terrible. Solo digo.

cosas legales aburridas

Por la presente se otorga permiso, sin cargo, a cualquier persona que obtenga una copia de este software y los archivos de documentación asociados (el “Software”), para operar con el Software sin restricciones, incluidos, entre otros, los derechos de uso, copia, modificación, fusión , publicar, distribuir, otorgar sublicencias y/o vender copias del Software, y permitir que las personas a las que se les proporcione el Software lo hagan, sujeto a las siguientes condiciones:

El aviso de derechos de autor anterior y este aviso de permiso se incluirán en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA “TAL CUAL”, SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO, ENTRE OTRAS, LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN FIN DETERMINADO Y NO VIOLACIÓN. EN NINGÚN CASO LOS AUTORES O LOS TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE CUALQUIER RECLAMACIÓN, DAÑOS U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE CUALQUIER OTRO TIPO, QUE SURJA DE, FUERA DE O EN RELACIÓN CON EL SOFTWARE O EL USO U OTROS TRATOS EN EL SOFTWARE.