Crear gráficos de sirenas en Markdown trucos CSS - Aprender Marketing
CSS

Crear gráficos de sirenas en Markdown trucos CSS

sirena gráficos y diagramas de flujo están ganando popularidad, especialmente con El mensaje de GitHub que se mantienen originalmente en Markdown. Veamos qué son, cómo usarlos e igual de importantes: por qué.

Tal como usted puede querer incruste su demostración de CodePen directamente en su fuente de documentación, ya que sus gráficos y diagramas se encuentran junto al texto para ayudarlo a prevenirlos torneado – es decir desviación de la sincronización con el estado de su documento. Los comentarios igualmente inútiles, obsoletos o engañosos en su código pueden ser objetivamente peores que no comentarios, lo mismo ocurre con los gráficos.

Los gráficos de sirena van bien con pila de atasco y generadores de sitios estáticos, que continúan creciendo en popularidad. El maridaje es natural. Si bien los gráficos de Mermaid no son exclusivos de Markdown, están inspirados en Markdown. Usando las mismas abstracciones de marcado que proporciona Markdown para marcar el código, Mermaid se puede representar de la misma manera para gráficos y diagramas de flujo.Y Markdown es para Jamstack y sitios estáticos, al igual que la mantequilla de maní para mermelada.

Si su sitio se creó en Markdown, se procesó en HTML y tiene suficiente control para agregar un poco de JavaScript personalizado, entonces puede usar las ideas que discutimos en este artículo para satisfacer sus propias necesidades y aplicar gráficos con Mermaid convenientemente junto con el resto de Markdown. . ¿Ya existe el término «gráficos como código»? Debe ser.

Por ejemplo, suponga que está trabajando en un nuevo producto sofisticado y desea proporcionar una hoja de ruta en forma de Gráfico de gantt (o algún otro tipo – digamos diagramas de flujo, secuencias y diagramas de clase). Con Mermaid puedes hacer esto en un pequeño puñado de filas:

gantt
  title My Product Roadmap
  dateFormat  YYYY-MM-DD
  section Cool Feature
  A task           :a1, 2022-02-25, 30d
  Another task     :after a1, 20d
  section Rad Feature
  Task in sequence :2022-03-04, 12d
  Task, No. 2      :24d

Lo que hará un buen gráfico SVG como este:

Nueve líneas de código nos brindan un diagrama de Gantt completo que se puede usar para hojas de ruta de productos y similares.

Consejo profesional: Mermaid tiene un editor en vivo que te permite probarlo sin comprometerte sirena.en vivo.

Gráficos de sirena en Markdown

A Mermaid le va bien con Markdown porque se presenta como uno más bloque de código adjuntousando solo mermaid conjunto de sintaxis del lenguaje. Por ejemplo, este bloque de código:

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

… produce HTML <pre> elemento con el contenido del bloque de código dentro:

<pre class="mermaid"><code>graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;</code></pre>

Si usas un El procesador Markdown cumple con la especificación CommonMarkse verá más como esto:

<pre><code class="language-mermaid">graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
</code></pre>

El comportamiento predeterminado de la API de Mermaid espera un <div class="mermaid"> una etiqueta que contiene directamente el contenido, por lo que no <code> o <span> (a partir de una etiqueta de sintaxis), que puede ver al convertir de Markdown a HTML.

Delicadeza con JavaScript

Con un poco de JavaScript, es aconsejable tomar el HTML generado por Markdown y refinarlo en <div class="mermaid"> etiqueta a la que apunta Mermaid. Vale la pena señalar $element.textContent está dirigido aquí: Markdown codificará en HTML caracteres específicos (por ejemplo, > en &gt;) que utiliza Mermaid. También filtra todos los elementos HTML erróneos heredados de <pre> elemento.

// select <pre class="mermaid"> _and_ <pre><code class="language-mermaid">
document.querySelectorAll("pre.mermaid, pre>code.language-mermaid").forEach($el => {
  // if the second selector got a hit, reference the parent <pre>
  if ($el.tagName === "CODE")
    $el = $el.parentElement
  // put the Mermaid contents in the expected <div class="mermaid">
  // plus keep the original contents in a nice <details>
  $el.outerHTML = `
    <div class="mermaid">${$el.textContent}</div>
    <details>
      <summary>Diagram source</summary>
      <pre>${$el.textContent}</pre>
    </details>
  `
})

Ahora que nuestro HTML tiene el formato correcto, implementemos Mermaid para renderizar.

Usando la sirena

Sirena se publica como paquete npmpara que pueda obtener una copia utilizando un CDN que conozca el paquete, p. desempaquetar. Deberá utilizar el código minimizado (por ejemplo, mermaid.min.js) en lugar de la exportación predeterminada de mermaid.core.js. Por ejemplo:

<script src="https://unpkg.com/[email protected]/dist/mermaid.min.js"></script>

es la sirena también Listo para ESM para que pueda usar Skypack para cargarlo también:

<script type="module">
  import mermaid from "https://cdn.skypack.dev/[email protected]";
</script>

Puede parar aquí mismo si quiere simplificar las cosas. Por defecto, la Sirena lo hará se inicializa automáticamente cuando el documento está listoSiempre que refine Markdown-to-HTML con JavaScript, mencionado anteriormente: antes de cargando en Mermaid – estarás listo.

Sin embargo, Mermaid tiene algunas configuraciones que vale la pena configurar:

// initialize Mermaid to [1] log errors, [2] have loose security for first-party
// authored diagrams, and [3] respect a preferred dark color scheme
mermaid.initialize({
  logLevel: "error", // [1]
  securityLevel: "loose", // [2]
  theme: (window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches) ?
    "dark" :
    "default" // [3]
})
  1. logLevel le dará un poco más de visibilidad para cualquier error que pueda ocurrir. Si quieres ver más información, puedes seleccione un nivel más detallado (o viceversa).
  2. securityLevel se refiere a nivel de confianza para la fuente del gráficoSi está satisfecho de que son autores, entonces "loose" es bueno. Si se trata de contenido generado por el usuario, probablemente sea mejor dejarlo "strict" ubicación predeterminada.
  3. theme cambios estilización de los diagramas representadosAl consultar el esquema de color preferido y usar un operador ternario, podemos especificar "dark" según sea apropiado.

¡Todos juntos ahora!

Estos son algunos ejemplos de gráficos de sirenas en Markdown:

aguas más profundas

Esta estrategia es especialmente efectivo porque es progresivo progresivo: si JavaScript está deshabilitado, la fuente original de Mermaid se muestra tal cual. Sin infracción.

También hay un completo Interfaz de línea de comando de sirena que, si está interesado en el estudio, podría usarse para mostrar diagramas que el servidor representa completamente. Entre la CLI de Mermaid y el generador en línea, incluso es posible involucrarse en cualquier proceso de construcción que utilice para generar una instantánea de un gráfico y mostrarlo como <img> copia de seguridad en lugar de código fuente.

Esperamos ver más integraciones naturales de Mermaid como esta, ya que Mermaid continúa creciendo en popularidad. La utilidad de tener gráficos y diagramas visuales junto con la documentación es innegable, desde hojas de ruta de productos hasta árboles de decisión y todo lo demás. Este es un tipo de información que es simplemente difícil de documentar solo con palabras.

Los gráficos de sirena abordan esto de una manera que garantiza que la información se pueda administrar y mantener junto con otra documentación.

Deja una respuesta

Tu dirección de correo electrónico no será publicada.

Botón volver arriba