Publicar bloques de código en un sitio de WordPress | Programar Plus ▷ Tutoriales

Publicado originalmente en febrero de 2014, ahora actualizado / corregido / ampliado.

Así que ha instalado WordPress y quiere escribir un blog sobre el código. ¡Hurra! Eres un héroe y agradezco en mi nombre a los programadores de todas partes. Esto es lo que deberá hacer y pensar para poder publicar bloques de código.

El HTML de un “bloque de código”

Hay un elemento específico para el código: <code>. Yo diría que es semánticamente correcto envolver todos y cada uno de los códigos en él. Las hojas de estilo predeterminadas del navegador lo dejan como elemento en línea, y le recomiendo que lo deje así para que pueda usarlo dentro de las oraciones como lo hice en la última oración.

Pero querrá usar un elemento a nivel de bloque para envolver un bloque de código. <pre> es el elemento perfecto para eso, ya que naturalmente retiene los espacios en blanco. “Pre” como en “Texto preformateado”. Múltiples espacios se mostrarán como múltiples espacios en lugar de colapsar en un solo espacio como sucede normalmente en HTML. Eso es perfecto para el código, porque probablemente querrá usar sangría en un bloque de código y no querrá recurrir a ninguna   engaños.

Entonces:

<pre><code>Your 
   
   block
  
       of

   code
 
 here.</code></pre>

Desactiva el editor “Visual”

De forma predeterminada, WordPress le permite cambiar entre las pestañas Visual y Texto en el editor.

Para ti, el editor visual tiene que desaparecer. Nunca lo usarás. Desea tener un control total del texto que está escribiendo y desea que permanezca tal como lo escribe cuando lo guarda.

Apágalo debajo Usuarios> Su perfil

¿Vas a escribir un blog en Markdown o no?

Aquí en Programar Plusno lo hago, pero si pudiera retroceder en el tiempo hasta el principio, probablemente lo haría. En la mayoría de los blogs posteriores que he hecho, uso Markdown y lo prefiero. Si va a hacerlo, le sugiero que use la función Markdown de Jetpack.

Para publicar un bloque de código en Markdown, una forma es sangrar ese código cuatro espacios en cada línea, así:

Yadda yadda yadda. I'm a *paragraph* in Markdown. Here's a [link to Google](http://google.com). Here's a block of code:

    <div>
       <p>I'm some code.</p>
    <div>

Another paragraph here.

Hacer eso manualmente envejecerá muy rápido. Por lo tanto, querrá reemplazar los botones de su editor con botones de Markdown. Parece que el complemento Markdown Quicktags puede hacer eso.

Lo bueno de usar Markdown es que no tiene que preocuparse por escapar del código. Entonces, esos corchetes angulares no son una amenaza de renderizado, Markdown los escapará por usted. En otras palabras, todos esos corchetes angulares (<) en el ejemplo HTML anterior se convertirá en < y, por lo tanto, se muestra en la pantalla como un corchete angular en lugar de confundir al navegador haciéndole pensar que está apareciendo una etiqueta HTML.

Ese ejemplo de Markdown anterior se convertirá en esto antes de que llegue al navegador:

<p>Yadda yadda yadda. I'm a <em>paragraph</em> in Markdown. Here's a <a href="http://google.com">link to Google</a>. Here's a block of code:</p>

<pre><code>&lt;div&gt;
   &lt;p&gt;I'm some code.&lt;/p&gt;
&lt;div&gt;</code></pre>

<p>Another paragraph here.</p>

Si está interesado en bloguear en Markdown, tiene algunas opciones. Jetpack, el complemento creado y mantenido por Automattic, ahora lo ofrece como parte de su mega paquete de ofertas. En este momento, uso WP-Markdown aquí en Programar Plus(sé que dije que no uso Markdown, pero lo hago para los foros y comentarios, pero no para blogs).

Dos que no he probado personalmente son Typewriter y Markdown en Saved Improved.

Sin embargo, aquí hay una limitación bastante importante. Observe que la sangría de cuatro espacios se convierte en una <pre><code> bloque, pero no hubo oportunidad de agregar atributos a esas etiquetas. Los atributos (como clases y atributos de datos *) son una necesidad común. Es posible que desee utilizar un resaltador de sintaxis (hablaremos de ellos más adelante) que requiere algunos atributos para hacer su trabajo. O tal vez desee identificar el bloque de código de alguna manera por idioma.

Más conveniente que sangrar, muchos “sabores” de Markdown (incluida la versión Jetpack) admiten la protección de código, que consiste en colocar bloques de código dentro de comillas triples:

```
<div>
  <p>I'm some code.</p>
<div>
```

Llamaría a esto directamente mejor. Es más fácil saltar a un bloque de código mientras se escribe sin tener que preocuparse por la sangría. Además, el código tiene su propia sangría, por lo que es bueno comenzar a ras de la izquierda con eso.

También puede especificar el idioma directamente en la sintaxis de Markdown. Entonces nuestro ejemplo podría ser:

```html
<div>
  <p>I'm some code.</p>
<div>
```

Lo que da:

<pre><code class="html">&lt;div&gt;
  &lt;p&gt;I'm some code.&lt;/p&gt;
&lt;div&gt;
</code></pre>

Si NO usa Markdown, deberá escapar del código.

Los bloques de código CSS rara vez necesitan escapar, pero HTML seguro que sí, y JavaScript a veces tiene HTML (así como casi todos los lenguajes de backend), por lo que también puede suponer que necesita escapar de todo el código.

Podrías hacerlo manualmente convirtiendo todos los

Prefiero usar un complemento llamado Code Markup para esto. Simplemente escapa automáticamente de cualquier cosa que encuentre dentro <code> etiquetas para que nunca tengas que pensar en ello.

Debido a que uso ese complemento en este sitio, puedo hacer cosas como:

<pre data-lang="HTML"><code class="language-markup"><div>
  <p>I'm some code.</p>
<div></code></pre>

Y funciona muy bien. Sin escapatoria. Control total de atributos.

Manejo del resaltado de sintaxis

Recuerde que una opción para resaltar bloques de código de sintaxis no es resaltar sintaxis. Ciertamente, esa sería la forma más rápida y sencilla. Pero es posible que lo desee. Personalmente me gusta. Me gusta cómo se ve. Aquí tienes algunas opciones.

Lo que esencialmente sucede con cualquier resaltador de sintaxis es que fragmentos de código terminan envueltos en <span>s con nombres de clases que colorea con CSS. La elección es una cuestión de características.

Prism.js

Aquí, en CSS-Tricks, uso (y recomiendo) Prism de Lea Verou, ya que funciona con los de inmediato. Es pequeño, rápido y (mi favorito) como nombres de clase racionales para el estilo. Usted elige qué idiomas desea que admita al descargarlo.

También utilizo ese complemento de escape, lo que significa que no necesito escapar de HTML dentro de las etiquetas de código, así que nuevamente se ve así:

<pre><code markup="tt" class="language-markup"><div>
  <p>I'm some code.</p>
<div></code></pre>

Ese class="language-markup" en la etiqueta de código es lo que Prism recoge para resaltar la sintaxis. Funciona automáticamente en todo el código que encuentra con ese patrón de nombre de clase de forma predeterminada, pero puede usar la API en su lugar si desea hacer lo suyo.

Embellecer

Uno extremadamente popular es google-code-prettify. Para resaltar la sintaxis de un bloque, pones class="prettyprint" en el código o en la etiqueta previa.

Tiene un tamaño de archivo más grande que Prism, pero una ventaja es que detecta automáticamente el idioma (y admite un montón de idiomas), por lo que debería funcionar en casi cualquier cosa sin tener que especificarlo.

Otros

Investigando un poco, hay muchos más de los que no puedo responder, pero parece que funcionarán: Rainbow, SyntaxHighlighter, Chili (jQuery), JSHighlighter, jQuery.Syntax (jQuery), GeSHi, Lighter (MooTools) , highlight.js, SHJS y Pygments (Python).

Decidir

Para decidir entre estos, puede pensar en estas cosas:

¿Qué idiomas necesito principalmente para admitir?
¿Quiero mostrar los números de línea?
¿Necesito poner enlaces dentro del código?
¿Quiero poder resaltar partes del código o líneas?
¿Tengo bloques de código heredados que necesito admitir? ¿En qué formato están?
¿Es el código fácil de copiar y pegar? ¿Quiero funciones que me ayuden con eso?
¿Está bien el resaltado de sintaxis del lado del cliente o quiero que suceda en el lado del servidor?

Identificación visual de bloques de código

Creo que es un buen toque poder ver de un vistazo qué tipo de código es un bloque de código. En este sitio, lo hago a través de un atributo en el bloque mismo, luego le doy estilo al valor de ese atributo como parte de la pantalla. Puede verlo en acción en la mayoría de los bloques de código que se muestran aquí (asumiendo que está mirando el sitio en sí, no leyendo el contenido distribuido en otro lugar).

Así es como puede mostrar visualmente un atributo particular en el bloque de código (¡el estilo depende totalmente de usted!):

pre[data-language-display]:before {
  content: attr(data-language-display);
}

Manejo del código heredado

Si ya tiene un montón de bloques de código en un sitio, le recomiendo que elija un resaltador de sintaxis cuyas características le gusten para su uso actual y futuro. Luego, encontrar una manera de hacerlo funcionar para los bloques más antiguos.

Por ejemplo, digamos que tengo un bloque de código heredado que está marcado así:

<pre><code class="javascript">
  var thing = document.getElementById("thing");
</code></pre>

Ese no es el nombre de clase correcto para Prism. Entonces podría usar jQuery para hacer algo como:

$("code.javascript")
  .removeClass("javascript")
  .addClass("language-javascript");

Y asegúrese de que JavaScript se ejecute antes que Prism. También podría aprovechar la oportunidad para $ .trim () el código porque, como se escribió arriba, hay un retorno adicional en la parte superior e inferior que podría afectar el estilo del bloque de código.

Me refiero a esto solo como un ejemplo. El punto general es: puede manipular los bloques de código heredados según sea necesario para adaptarse al nuevo formato.

Usando un complemento

Hay muchos, muchos complementos para esto. Esta publicación está orientada principalmente a manejar esto por su cuenta, ya que generalmente ese es el tipo de control que me gusta. Pero estoy seguro de que hay muchos complementos bien hechos para esto. Me temo que no puedo recomendar uno, pero esto es lo que buscaría:

Buenas críticas / calificaciones / parece que está actualizado
No te obliga a hacer nada extraño / propietario con bloques de código. Por ejemplo, use un [shortcode]. Esto te vinculará a ese complemento para siempre.
Admite los idiomas y las funciones que necesita (y solo las cosas que necesita, no carga todo bajo el sol).

Ayuda de terceros

Al crear la función Plumas integradas en CodePen, sabíamos que mostrar demostraciones y código en publicaciones de blog era una especie de molestia, por lo que nos propusimos hacerlo más fácil.

A continuación, se muestra un ejemplo de un lápiz integrado, con el código CSS predeterminado:

Vea la Coloración dinámica de imágenes con lápiz de Noah Blon (@noahblon) en CodePen.

No necesito preocuparme por el resaltado de sintaxis, el escape ni nada, y también obtengo el beneficio de mostrar la demostración renderizada.

Muchos de los otros sitios de edición de código ofrecen código incrustado, así como JSFiddle y JSBin. GitHub Gists también puede ser útil para esto. Quizás mi razón favorita para usar herramientas de terceros para esto es que puede actualizar la demostración allí y la publicación del blog automáticamente tiene el nuevo código. No tienes que actualizar cosas en dos lugares.

¿Tiene su propia forma de manejar bloques de código en un sitio de WordPress? Comparte.