WMarkDown WMarkDown

Menu
Content
Por KyMAN. Creado a fecha 2021/05/02. Última modificación a fecha 2021/05/13.

WMarkDown

WMarkDown es un pequeño conjunto de librerías que aprovechan la falta de estandarización de MarkDown y MediaWiki para establecer un estándar de formato de texto para documentar proyectos, aplicaciones o simplemente mostrar información en HTML procesado a partir de una mezcla de ambos lenguajes.

WMarkDown, de primeras, está desarrollado en PHP, aunque puede extenderse a otros lenguajes como JS, Python, C#, Java y similares por su estructuración interna, de forma fácil y sencilla. También se puede ayudar de librerías externas como MermaidJS para generar diagramas, entre otras posibles opciones.

El nombre de WMarkDown viene de sus desarrolladores, el equipo Whalers, y como nombre final sería Whalers MarkDown, compactando el nombre de los desarrolladores WMarkDown y compactando en siglas, WMD. La extensión de los ficheros WMarkDown sería ".w.md" para compatibilizar con la extensión estandar de MarkDown.

¿Cómo funciona?

Este sistema se basa en la compilación o formateo de un String, o conjuntos de String en caso de estar fragmentado, los cuales pasarán, a partir de un archivo HTML original con las partes diferenciadas sobre unas variables internas las cuales se usarán para establecer la información del fichero HTML final, tras el formateo del String que conformaría el WMarkDown.

En este caso, para llevar a cabo dicha operación, y como idea de integración documental sobre proyectos, se crea un directorio donde se añaden los archivos MarkDown o WMarkDown, pudiendo usar directorios para ordenarlos y estructurarlos, y tras ello, cada vez que se ejeucte el programa WMarkDown, compila dichos ficheros en HTML y los integra dentro del proyecto de forma directa.

Por KyMAN. Creado a fecha 2021/06/29. Última modificación a fecha 2021/06/29.

Proyectos

Los siguientes proyectos hacen uso de WMarkDown de forma reconocida por sus autores y verificado por el equipo de WMarkDown.

NOTA: Con el paso del tiempo puede que alguno de estos proyectos deje de funcionar o de estar activo así como evolucionar y dejar de hacer uso de esta herramienta sin que el equpo de WMarkDown lo sepa por lo que puede haber algún error, aunque se intentará que no los halla.

Los siguientes proyectos son de los que WMarkDown se sirve para existir.

Por KyMAN. Creado a fecha 2021/05/02. Última modificación a fecha 2021/05/05.

Configuración

Todo esto que hemos comentado se llevará a cabo a partir de una configuración la cual reside en múltiples partes del proyecto, y las mismas tendrán diferente prioridad a la hora de ser trabajadas, pudiendo opacar parámetros o valores sobre otros. Esto está diseñado así para flexibilizar la alteración de la configuración y que la configuración original persista.

Parámetros de configuración

La configuración se dividirá en parámetros los cuales responden como un diccionario donde se les pone un nombre como llave y luego con valor o conjunto de valores dependiendo del caso. Dichos parámetros los vamos a ir trabajando a continuación.

default_value

El valor por defecto hace alusión a un valor el cual no ha sido facilitado por nadie y que el propio programa no es capaz de sacar, por lo que se le establece este valor por defecto. Es usado sobretodo cara la configuración, entre otros aspectos, para valores que no se encontraron y no se les dio un valor por defecto.

Dicho valor puede ser cualquier cosa y se aconseja que se implemente por un administrador o desarrollador, en caso de no ser ninguno de ellos se aconseja no cambiar.

Su valor por defecto es null.

nulls

Este valor es de tipo Booleano y verifica si se admite, por defecto, respuestas nulas a la hora de intentar acceder a un parámetro de la configuración. El permitir o no permitir valores nulos como valor a una llamada de la configuración puede conllevar a variar el resultado. El no permitir nulos no implica que no pueda responder un valor nulo puesto que es para gestionar el orden de priodidad cara una posible respuesta.

Para información acerca de los niveles de la configuración ir a Niveles de prioridad.

Pongamos un ejemplo, supongamos que tenemos un parámetro de configuración que no existe, y tenemos la configuración por defecto, y lo llamamos. Si le ponemos un valor por defecto éste retornará dicho valor por defecto, en caso contrario, retornará null aún a pesar de no tenerlo permitido, por no haber otra opción de valor, cogiendo el valor por defecto establecido con el parámetro anterior.

                    
  • Language php
  • Lines 7
  • Characters 319
// Este ejemplo retornará "por_defecto". echo "Con valor por defect: " . $wmarkdown->settings("no_existo", null, "por_defecto", false) . "<br />\n"; // Mientras que éste otro retornará null. echo "Sin valor por defect: " . $wmarkdown->settings("no_existo", null, null, false) . "<br />\n";

wmarkdown_root

Nos indica la ruta absoluta a nuestro proyecto WMarkDown.

root

Nos indica la ruta absoluta a nuestro proyecto donde queremos implementar el WMarkDown.

documentation_path

Nos indica la ruta relativa desde la dirección establecida en el parámetro "root" de la configuración donde se encuentran los ficheros de documentación WMarkDown.

html_files

Indica la ruta relativa desde la dirección establecida en el parámetro "root" donde se encontrará la pequeña base de datos JSON que almacena el Path de los ficheros HTML generados a partir de la documentación. Dicho fichero será usado por el WMarkDown para identificar los ficheros HTML creados, los cuales serán eliminados para su actualización cada vez que se ejecute el WMarkDown para generar los HTML de la documentación.

public_path

Indica la ruta relativa desde la dirección establecida en el parámetro "root" del directorio público del proyecto donde establecer los archivos HTML que dan forma a los ficheros WMarkDown.

html_base

Indica la ruta relativa desde la dirección establecida en el parámetro "root" donde se encuentra el archivo HTML que se usará de base para generar todos los documentos HTML de la documentación.

default_modules

Este parámetro implementa los diferentes módulos que se quieran aplicar al WMarkDown y los ordena a partir de un diccionario. Su valor por defecto es el siguiente:

                    
  • Language json
  • Lines 8
  • Characters 319
{ "lists" : "\\WMarkDown\\Modules\\Lists", "headers" : "\\WMarkDown\\Modules\\Headers", "code_blocks" : "\\WMarkDown\\Modules\\CodeBlocks", "paragraphs" : "\\WMarkDown\\Modules\\Paragraphs", "font_formats" : "\\WMarkDown\\Modules\\FontFormats", "checks" : "\\WMarkDown\\Modules\\Checks" }
Cambiar el orden de estos elementos puede conllevar a que se solapen por el patrón de búsqueda con el que se gestionan, como por ejemplo los párrafos, que buscan todo conjunto de líneas juntas para unificarlas en un único párrafo, pueden solapar cabeceras, listas, etc.

hash_alphabet

Alfabeto a usar para generar los Hashes Random para generar identificadores automáticos no visibles directamente sobre los usuarios finales. Este parámetro simplemente almacena caracteres con los que trabajar para generar dichas cadenas aleatorias. El valor puede ser un String o un Array de caracteres.

Hay que tener en cuenta que al ser usado para determinar identificadores únicos entre diferentes entornos y lenguajes, los resultados nunca podrán iniciarse como un caracter numérico y por lo tanto, obliga a que exista por lo menos un caracter no numérico dentro de la cadena.

Se le puso la cadena de Base58 de Bitcoin con la idea de que los caracteres sean identificables a simple vista, eliminando los caracteres que puedan dar lugar a confusión como la O mayúscula contra el 0.
IMPORTANTE: Es importante destacar que ha de haber por lo menos dos caracteres diferentes, y que repetir caracteres dentro de una misma cadena simplemente les dará a los caracteres repetidos mayor probabilidad contra los no repetidos, así como a más repeticiones más probabilidad de que salgan en las cadenas finales. El hacer uso de cadenas vacías o con un solo caracteres implicará la creación de bucles infinitos por el hecho de no conseguir una cadena única. También cabe destacar que solo permitirá caracteres comprendidos en el alfabeto inglés de la A a la Z tanto mayúsculas como minúsculas, distinguiendolos como caracteres diferentes; dígitos y guiones bajos, el resto de caracteres serán descartados de su uso.

Ejemplos de implementación pueden ser los siguientes:

                    
  • Language php
  • Lines 24
  • Characters 938
// Aquí lo dejaríamos por defecto. $wmarkdown = new WMarkDown(); // Aquí implementamos una cadena de caracteres reducida basada en una palabra. $wmarkdown = new WMarkDown([ "hash_alphabet" => "Hola_a_todos" ]); // Aquí cambiamos la cadena de Base58 por defecto a una Base64. $wmarkdown = new WMarkDown([ "hash_alphabet" => "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/" ]); // Aquí cambiamos la cadena de Base58 por defecto a una Base64 pero como Array. $wmarkdown = new WMarkDown([ "hash_alphabet" => [ "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "+", "/" ] ]);

Todas las opciones anteriores son válidas para funcionar. Ahora veamos ejemplos de resultados según metamos unas cadenas u otras.

                    
  • Language php
  • Lines 47
  • Characters 1655
$wmarkdown = new WMarkDown(); $wmarkdown_b = new WMarkDown([ "hash_alphabet" => "Haha" ]); $wmarkdown_c = new WMarkDown([ "hash_alphabet" => "¡Hola a todos!" ]); $wmarkdown_d = new WMarkDown([ "hash_alphabet" => [ "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "+", "/" ] ]); $hashes = []; while(count($hashes) < 10) $hashes[] = implode(", ", [ $wmarkdown->get_hash(), $wmarkdown_b->get_hash(), $wmarkdown_c->get_hash(), $wmarkdown_d->get_hash() ]); print_r($hashes); /* Un ejemplo de resultado podría ser: Array ( [0] => Z6VqHQSjVai, HhHHaaHHhHH, saHloHoloot, H9CkFZsRRWi [1] => aXGoD1FKsDf, aaHahahHaah, aoasoodooll, Ju3AT2FMolq [2] => oiUAFV1yxts, ahaaaaaaaHa, taHtadaHsHs, kGYZhPE8jRj [3] => xBiyMXuTcZ4, aahaHHHaaaH, soHoasdtolt, LniSyRb2Gib [4] => cv5wY5rVRAH, hHhhaahhHaa, ddstoaolHod, bNDoLasg8WZ [5] => ZnHW61uyJJQ, aHHHhaaHaah, atHltdltoto, OhFmtywPlge [6] => bi5TNw5vc4p, HaHaHaHhaaa, HtloaaHtaHt, ZieE4Jj6gx6 [7] => vNCPVpwm1YM, HHaaHaaaHHH, aodtsttHoda, NSrEx8mBZ8X [8] => zYd5FJXkYK5, aaaaaaHahHa, dadoodootda, O4uZBdZB5U4 [9] => rz4k1ydc9YR, aaaahaahaHa, oodaldatsao, eIFFpkdpmM4 ) */

Es importante mencionar que a menos caracteres distintos, mayor es la probabilidad de que se repitan los Hashes Random y por tanto, mayor consumo relativo, además de correr el riesgo de entrar en un bucle infinito por haber consumido todas las posibilidades aleatorias según le haga falta al WMarkDown.

Su valor por defecto es la cadena Base58 de Bitcoin, la cual es 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz

hash_length

Este parámetro indica la longitud de cada Hash Random que se vaya a crear, siendo mínimo 1 y máximo los que se deseen. Hay que tener en cuenta que a menos caracteres más probabilidad de repetición, además de mayor facilidad para acabar con todas las posibilidades dadas, y es importante tener en cuenta dicho valor, sobretodo cuando trabajemos un número pequeño de caracteres para la creación de los Hash Random. Un ejemplo de éste puede ser el siguiente:

                    
  • Language php
  • Lines 40
  • Characters 1244
$wmarkdown = new WMarkDown(); $wmarkdown_b = new WMarkDown([ "hash_length" => 3 ]); $wmarkdown_c = new WMarkDown([ "hash_length" => 20 ]); $wmarkdown_d = new WMarkDown([ "hash_length" => 7 ]); $hashes = []; while(count($hashes) < 10) $hashes[] = implode(", ", [ $wmarkdown->get_hash(), $wmarkdown_b->get_hash(), $wmarkdown_c->get_hash(), $wmarkdown_d->get_hash() ]); print_r($hashes); /* Un ejemplo de resultado puede ser el siguiente: Array ( [0] => aQEVtJ8Zmee, Ddd, w369wRfC7gcaik7c5SEP, u3thce2 [1] => DPMWqquJvYm, m2h, CDFMWW2VoHdsK776p4Hq, p5NqBFt [2] => VSmhZo8eFbs, jwz, rfTw2p8U5tUZGPDK6vVC, f4oybwX [3] => itKA4e4Zo5a, mqg, AMLDJQW8CdHp7XwXWNnj, G2cQtuY [4] => dMHcTSD8VH2, Uo9, X8ZLvrKdVUHr1ZDJnyCA, JJgW288 [5] => hQBa83ER9yH, ZFN, EVwD2drQiy8akniWpuba, dYgaH5c [6] => rqj9T3d3zXB, C9L, AuRPTjfp3usxLtAm3Q3N, Djy2RYm [7] => siYZXPYEkHT, sCT, TiBjCAKGwNrP6vMqXdA6, MV62dUa [8] => Ze3HBZFruaG, Lvk, YVMcpxFjZVcvrMz6JPwD, N2pwQFk [9] => paoSrYYacZx, FB3, VVje5rZgQQTfxsuTFTa7, Zy4YVaT ) */

Su valor por defecto es 11.

special_code_blocks

Este parámetro determina en un Array los bloques de código especiales, es decir, aquellos que pueden ser usados sobre un entorno cliente para resolver o crear cosas, como puede ser una extensión JS como por ejemplo MermaidJS para la creación de diagramas. Estos bloques se ignorarán para su tratamiento profundo como el Syntax Highlighting entre otros procesos que puedan llevar.

Su valor por defecto es "mermaid".

default_title

Título por defecto para archivos que no contienen ninguna cabecera de referencia para ser nombrados.

El valor por defecto es "Unknown", por el hecho de desconocer el contenido del mismo.

title

El título de una página Web que se presenta en la pestaña o barra de título por lo general viene el nombre del sitio o concepto a mirar, acompañado en muchas ocasiones del contenido que se quiere mostrar. En este caso se especifica el nombre del sitio, que por defecto es WMarkDown pero debe ser cambiado por el nombre del proyecto donde se integre éste.

Fichero original

El archivo de configuración original se encuentra en el directorio JSON que se encuentra en el directorio raíz del proyecto, y viene siendo un fichero llamado WMarkDown.settings.json. Aquí se encontrará toda la configuración por defecto de la aplicación. Si falta alguno de los parámetros de configuración la aplicación puede dar errores.

Por defecto, dicho fichero es tal que así:

                    
  • Language json
  • Lines 23
  • Characters 898
{ "default_value" : null, "nulls" : true, "wmarkdown_root" : "/mnt/d/Projects/WMarkDown", "root" : "/mnt/d/Projects/WMarkDown", "documentation_path" : "/WMD", "html_files" : "/JSON/html.files.json", "public_path" : "/Public", "html_base" : "/HTML/WMarkDown.base.html", "default_modules" : { "lists" : "\\WMarkDown\\Modules\\Lists", "headers" : "\\WMarkDown\\Modules\\Headers", "code_blocks" : "\\WMarkDown\\Modules\\CodeBlocks", "paragraphs" : "\\WMarkDown\\Modules\\Paragraphs", "font_formats" : "\\WMarkDown\\Modules\\FontFormats", "checks" : "\\WMarkDown\\Modules\\Checks" }, "hash_alphabet" : "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz", "hash_length" : 11, "special_code_blocks" : ["mermaid"], "default_title" : "Unknown", "title" : "WMarkDown" }

Niveles de prioridad

  1. Configuración dada en el input
  2. Creando un archivo JSON.
  3. Archivo JSON original.
Por KyMAN. Creado a fecha 2021/05/05. Última modificación a fecha 2021/05/11.

FAQ (Preguntas frecuentes)

Ante este proyecto, que aunque no es muy grande, tiene su extensión documental, le pondremos un apartado de resolución de dudas y preguntas rápidas que vayan surgiendo, el cual es este. Dicho apartado puede actualizarse sin que se actualice el proyecto en cuestión cuando se consxidere que la pregunta es muy recurrente o se ve importante.

Escape de caracteres

Al estar en un entorno con un lenguaje de etiquetas donde un caracter puede significar un concepto entero de formato o de elemento, por lo tanto, sería un caracter no usable a nivel de texto o resultado final. Para evitar esto existe un sistema que permite escapar dichos caracteres cuando éstos se tratan de un elemento de línea, es decir, un elemento que pueda estar incluído dentro de una línea de texto o un párrafo, como puede ser una negrilla o una cursiva. Para realizar dicho escape hemos de usar el el caracter Slash ("\", escapándose así "\\"). Dicho caracter también permite escaparse a sí mismo, por lo que si se quiere poner un Slash ha de ponerse doblemente, o en caso de estar en un IDE o entorno donde el caracter de escape sea Slash también, ha de duplicarse con el escape correspondiente ("\\\\").

Listas numéricas y cabeceras

Cuando hablamos de MarkDown, una cabecera se inicia con el caracter Hash ("#"), sin embargo, cuando hablamos de listas ordenadas numéricas en MediaWiki, el caracter usado también es el Hash. Para diferenciar ambos a nivel del texto se establece que una cabecera tiene al menos dos saltos de línea en su parte inferior, siendo una línea única separada del resto de bloques de texto, mientras que las listas son de al menos dos elementos y solo hay un salto de línea que separa cada línea, quedando como un único bloque. Un ejemplo de ello puede ser lo siguiente:

                    
  • Language txt
  • Lines 38
  • Characters 867
# Esto es una cabecera Esta cabecera se inicia al principio de todo. # Esto es otra cabecera Esta sería una cabecera que está por el medio del texto. ## Cabecera de segundo nivel Esto sería una cabecera de segundo nivel. # Primer elemento. # Segundo elemento. # Tercero elemento. # Cuarto elemento. Y esto que hemos puesto es una lista ordenada numérica que empieza en 1 y se incrementará 1 por cada línea puesta. Para evitar confusiones, también se permite el uso del caracter numérico, el cual determina el inicio de la lista, y para equiparar el ejemplo anterior tendríamos: 1. Primer elemento. 1. Segundo elemento. 1. Tercero elemento. 1. Cuarto elemento. Y esto mismo, siguiendo la esquemática de MarkDown, sería: 1. Primer elemento. 2. Segundo elemento. 3. Tercero elemento. 4. Cuarto elemento. jojo

Diferentes opciones para lo mismo

Se usan diferentes opciones para llegar a un mismo fin para poderlo usar como alternativa o incluso, como escape de sí mismo, por ejemplo, cuando ingresamos un bloque de código para presentar como se haría otro bloque de código dentro de WMarkDown usaríamos las distintas formas de llamar a los bloques de código, una que represente la principal, y la otra que represente la interna. Por ejemplo:

                    
  • Language md
  • Lines 6
  • Characters 123
---md Esto es MarkDown y a continuación pongo un bloque de código. ```js console.log("Esto es JavaScript."); ``` ---
Por KyMAN. Creado a fecha 2021/05/11. Última modificación a fecha 2021/05/16.

Módulos

La plataforma se basa en módulos que van formateando el texto que se le pase para ir haciendo un resultado HTML a partir del texto plano. Un simple párrafo o una cabecera que conforma a su vez el menú, son módulos integrados y que a su vez pueden ser modificados, añadidos o eliminados.

Módulos por defecto

En este apartado se irán poniendo todos los módulos que han sido incluídos por defecto para dar lugar a todo el gestor documental.

Por KyMAN. Creado a fecha 2021/05/12. Última modificación a fecha 2021/05/12.

Cabeceras (Headers)

Las cabeceras o Headers son equivalentes a las cabeceras de HTML, desde el nivel 1 hasta el 6, los cuales se representan de la siguiente forma:

                    
  • Language md
  • Lines 6
  • Characters 418
# Cabecera de nivel 1 <h1>Cabecera de nivel 1</h1> ## Cabecera de nivel 2 <h2>Cabecera de nivel 2</h2> ### Cabecera de nivel 3 <h3>Cabecera de nivel 3</h3> #### Cabecera de nivel 4 <h4>Cabecera de nivel 4</h4> ##### Cabecera de nivel 5 <h5>Cabecera de nivel 5</h5> ###### Cabecera de nivel 6 <h6>Cabecera de nivel 6</h6>
Para seguir las normas de HTML, no habrá más de 6 niveles de cabeceras.

Dichas cabeceras representan el título de cada sección, subsección o fragmento de la documentación, y en WMarkDown se usará también como guía para el menú, que navega por cabeceras para poder generar un OnePage documental completo.

Cuando se incluye un fichero externo con la propiedad "include" éste sumará el nivel de la cabecera en la que se encuentra la inclusión. En caso de no quererse ampliar o quererse ampliar solo ciertos niveles, existe una propiedad llamada "header_level" que permite establecer un nivel del cual partir en la siguiente inclusión.

                    
  • Language md
  • Lines 20
  • Characters 309
# Estamos en nivel 1. Contenido del nivel 1. ## Estamos en nivel 2. Contenido del nivel 2. [[include path/fichero_a.w.md]] [[header_level 0]] [[include path/fichero_b.w.md]] [[header_level 3]] [[include path/fichero_c.w.md]] [[header_level default]] [[include path/fichero_d.w.md]]

En el ejemplo dado, la inclusión de "fichero_a" se hará al nivel actual, el nivel 2, quedando todos los títulos herederos del nivel donde se encuentra; mientras que el segundo se hará sobre el nivel raíz; y finalmente, el "fichero_c" se pondrá a nivel hijo de 4.

Es importante mencionar que los niveles de inclusión suman al nivel del título donde se encuentre, siendo nivel 0 cuando no hay título; nivel 1 cuando hay título; y sucesivos. Por lo tanto, si a esta sucesión la ponemos en el nivel 3, se entiende que aquellos bloques que no están precedidos de ningún título está en el nivel 3; los que están precedidos de un título de nivel 1 será el nivel 4, y sucesivos.

Para poder restaurar los niveles contra el padre, simplemente tomaremos como valor de la propiedad "header_level" como "default".

Cara MediaWiki, las cabeceras se organizan con encapsulados de texto con el caracter igual ("="), donde el número de éstos que salga por cualquiera de los dos lados del encapsulado, será el nivel donde se encuentra, y siguiendo con la misma idea anterior, los niveles se encuentran entre 1 y 6 siendo éstos los siguientes:

                    
  • Language md
  • Lines 6
  • Characters 634
= Cabecera de nivel 1 = # Cabecera de nivel 1 <h1>Cabecera de nivel 1</h1> == Cabecera de nivel 2 == ## Cabecera de nivel 2 <h2>Cabecera de nivel 2</h2> === Cabecera de nivel 3 === ### Cabecera de nivel 3 <h3>Cabecera de nivel 3</h3> ==== Cabecera de nivel 4 ==== #### Cabecera de nivel 4 <h4>Cabecera de nivel 4</h4> ===== Cabecera de nivel 5 ===== ##### Cabecera de nivel 5 <h5>Cabecera de nivel 5</h5> ====== Cabecera de nivel 6 ====== ###### Cabecera de nivel 6 <h6>Cabecera de nivel 6</h6>
Por KyMAN. Creado a fecha 2021/05/16. Última modificación a fecha 2021/05/16.

Párrafos

Para poder hacer textos que estén dividos por párrafos de forma automática, WMarkDown entenderá que cuando halla más de un salto de línea consecutivo, éste separa párrafos o componentes, por lo que los textos sueltos se considerarán párrafos a ésta condición, por ejemplo.

WMarkDown HTML Resultado

                    
  • Language md
  • Lines 7
  • Characters 194
Este es un párrafo que continúa, aun a pesar de ser otra línea, y que sigue continuando por aquí. Este ya es otro párrafo pues se separa del anterior mediante dos saltos de línea.

                    
  • Language html
  • Lines 7
  • Characters 232
<p>Este es un párrafo que continúa, aun a pesar de ser otra línea, y que sigue continuando por aquí.</p> <p>Este ya es otro párrafo pues se separa del anterior mediante dos saltos de línea.</p>

Este es un párrafo que continúa, aun a pesar de ser otra línea, y que sigue continuando por aquí.

Este ya es otro párrafo pues se separa del anterior mediante dos saltos de línea.

Por KyMAN. Creado a fecha 2021/05/16. Última modificación a fecha 2021/05/16.

Formatos de fuente

Los formato de la fuente puede ser un tema muy extenso, sin embargo, por lo general, tienen una serie de patrones en uso, y pocos elementos de formatos quedan expuestos a no tener un patrón concreto, y de éstos últimos, por lo general solo se hace uso de dos: la negrilla y la cursiva. Esto da pie a considerar sólo el formato rápido por marcas de texto de éstos dos, el resto han de ser aplicados o por CSS o por HTML. Para poder aplicar ambos, podemos basarnos tanto en MediaWiki como en MarkDown, siendo de la siguiente forma:

Objetivo MediaWiki MarkDown HTML
Negrilla

                    
  • Language md
  • Lines 2
  • Characters 30
'''Negrilla''' """Negrilla"""

                    
  • Language md
  • Lines 2
  • Characters 26
**Negrilla** __Negrilla__

                    
  • Language html
  • Lines 1
  • Characters 27
<b>Negrilla</b>

Cursiva

                    
  • Language md
  • Lines 2
  • Characters 24
''Cursiva'' ""Cursiva""

                    
  • Language md
  • Lines 2
  • Characters 20
*Cursiva* _Cursiva_

                    
  • Language html
  • Lines 1
  • Characters 26
<i>Cursiva</i>

Negrilla y cursiva

                    
  • Language md
  • Lines 2
  • Characters 58
'''''Negrilla y cursiva''''' """""Negrilla y cursiva"""""

                    
  • Language md
  • Lines 2
  • Characters 50
***Negrilla y cursiva*** ___Negrilla y cursiva___

                    
  • Language html
  • Lines 1
  • Characters 56
<b><i>Negrilla y cursiva</i></b>

Por KyMAN. Creado a fecha 2021/05/11. Última modificación a fecha 2021/05/13.

Checks, Radios y Ticks

Como en cualquier sistema documental, ya sea una libreta de apuntes a mano o cualquier otro sistema digital, es importante contar con un sistema que permita mostrar elementos seleccionados y no seleccionados, una selección de elemento sobre un grupo, o Targets llevados a cabo, entre otras opciones de selección. Para ello se usarán los Checks, Radios y Ticks.

Aunque tanto los Checks, como los Radios como los Ticks se pueden usar independientemente, a nivel de HTML o programación, tienen funcionalidades diferentes que visualmente pueden identificar algo concreto, es por ello que se hace la siguiente distinción.

MediaWiki no tiene un medio dado para hacer dicha operación salvo el propio HTML; y MarkDown solo tiene la opción por defecto de hacer Checkboxes únicamente, con solo dos posiciones: activado o no desactivado. Aquí añadimos un nuevo estado puede puede considerarse un ternario como "estar en proceso" o que simplemente se ignore del resto de elementos seleccionados.

Para poder llevar a cabo todas estas distinciones se hace uso de encapsulados de apertura y cierre con corchetes para los Checks, paréntesis para los Radios y llaves o diamantes para los Ticks. Los caracteres que identifican el estado serían los siguientes:

  • _"-", "", "\", "=", "|", "·" o "?"_: Deshabilitado, en proceso, ignorado.
  • "*", "+", "X", "V", "Y" o "#": Seleccionado.
  • " " o "N": No seleccionado.
El sistema no diferencia mayúsculas de minúsculas, por lo que se pueden usar independientemente.
IMPORTANTE: El caracter "V" indicará Tick afirmativo siempre, independientemente del encapsulado.

Checks

Los Checks o Checkbox son iconos que representan si un elemento está seleccionado o no. Es usado en programación como casilla de selección o para visualizar si los elementos seleccionados, independientemente del número de elementos, agrupaciones de los mismos, etc. Éstos se identifican con los caracteres de apertura y cierre de corchete ("[" y "]") para encapsular su estado.

WMarkDown Resultado

                    
  • Language md
  • Lines 3
  • Characters 65
- [ ] No seleccioando. - [X] Seleccionado. - [-] Deshabilitado.

  • No seleccionado.
  • Seleccionado.
  • Deshabilitado.

Radios

Los Radios o RadioButtons son iconos que representan una selección única por grupo, aunque en WMarkDown puede ser usado independientemente a gusto del autor del texto. Dicho elemento se identifica por la encapsulación de los caracteres de apertura y cierre de paréntesis ("(" y ")").

WMarkDown Resultado

                    
  • Language md
  • Lines 3
  • Characters 65
- ( ) No seleccionado. - (X) Seleccionado. - (-) Deshabilitado.

  • No seleccionado.
  • Seleccionado.
  • Deshabilitado.

Ticks

Los Ticks son muy comunes cuando se trata de listas donde ir cubriendo objetivos, como una lista de la compra, donde no existe un recuadro o círculo donde se marcan los elementos. Se identifican mediante la encapsulación entre los caracteres de apertura y cierre de diamante ("<" y ">") o llaves ("{" o "}").

IMPORTANTE: Es importante destacar que los Ticks no tienen la opción de elemento deshabilitado por suponerse un elemento escrito.

WMarkDown Resultado

                    
  • Language md
  • Lines 19
  • Characters 283
Con diamantes: - < > No seleccionado. - <X> Seleccionado. - <-> Deshabilitado. Con llaves: - { } No seleccionado. - {X} Seleccionado. - {-} Deshabilitado. Uso del caracter V: - [V] Seleccionado. - (V) Seleccionado. - <V> Seleccionado.

Con diamantes:

  • No seleccionado.
  • Seleccionado.
  • Deshabilitado.

Con llaves:

  • No seleccionado.
  • Seleccionado.
  • Deshabilitado.

Uso del caracter V:

  • Seleccionado.
  • Seleccionado.
  • Seleccionado.

Por KyMAN. Creado a fecha 2021/05/13. Última modificación a fecha 2021/05/13.

Links

Los Links son los encargados de gestionar los vínculos entre páginas o dentro de la propia página, incluyendo vínculos a sitios externos. En este caso nos encontramos con que MarkDown y MediaWiki varían bastante el formato de los mismos por lo que la adaptación de ambos se basó en el lado del MarkDown y se extendió a la idea de MediaWiki, quedando como resultado que todo Link encabezado por el protocolo, ya sea HTTP, HTTPS, FTP, FTPS, SFTP, FILE, etc. Se considerará un Link.

En el siguiente ejemplo habrá una lista de Links a partir del protocolo en texto plano:

WMarkDown Resultado

                    
  • Language md
  • Lines 8
  • Characters 220
- https://git.k3y.pw/ - https://wmarkdown.k3y.pw/ - https://cdn.k3y.pw/ Incluso podemos poner un link como https://ur3.k3y.pw/ dentro de un texto o párrafo y éste será reconocido y formateado como Link HTML.

Incluso podemos poner un link como https://ur3.k3y.pw/ dentro de un texto o párrafo y éste será reconocido y formateado como Link HTML.

Pero los Links también se pueden formatear a partir del siguiente esquema:

WMarkDown HTML Resultado

                    
  • Language md
  • Lines 1
  • Characters 25
https://wmarkdown.k3y.pw/

                    
  • Language html
  • Lines 1
  • Characters 127
<a href="https://wmarkdown.k3y.pw/" title="https://wmarkdown.k3y.pw/" target="_blank">https://wmarkdown.k3y.pw/</a>

https://wmarkdown.k3y.pw/" title="https://wmarkdown.k3y.pw/" target="_blank">https://wmarkdown.k3y.pw/

                    
  • Language md
  • Lines 1
  • Characters 27
[https://wmarkdown.k3y.pw/]

                    
  • Language html
  • Lines 1
  • Characters 127
<a href="https://wmarkdown.k3y.pw/" title="https://wmarkdown.k3y.pw/" target="_blank">https://wmarkdown.k3y.pw/</a>

https://wmarkdown.k3y.pw/" title="https://wmarkdown.k3y.pw/" target="_blank">https://wmarkdown.k3y.pw/

                    
  • Language md
  • Lines 1
  • Characters 37
[https://wmarkdown.k3y.pw/ WMarkDown]

                    
  • Language html
  • Lines 1
  • Characters 95
<a href="https://wmarkdown.k3y.pw/" title="WMarkDown" target="_blank">WMarkDown</a>

https://wmarkdown.k3y.pw/" title="WMarkDown" target="_blank">WMarkDown

                    
  • Language md
  • Lines 1
  • Characters 38
[WMarkDown][https://wmarkdown.k3y.pw/]

                    
  • Language html
  • Lines 1
  • Characters 95
<a href="https://wmarkdown.k3y.pw/" title="WMarkDown" target="_blank">WMarkDown</a>

https://wmarkdown.k3y.pw/" title="WMarkDown" target="_blank">WMarkDown

                    
  • Language md
  • Lines 1
  • Characters 38
[WMarkDown](https://wmarkdown.k3y.pw/)

                    
  • Language html
  • Lines 1
  • Characters 95
<a href="https://wmarkdown.k3y.pw/" title="WMarkDown" target="_blank">WMarkDown</a>

https://wmarkdown.k3y.pw/" title="WMarkDown" target="_blank">WMarkDown

                    
  • Language md
  • Lines 1
  • Characters 68
[WMarkDown](https://wmarkdown.k3y.pw/ Página oficial de WMarkDown.)

                    
  • Language html
  • Lines 1
  • Characters 115
<a href="https://wmarkdown.k3y.pw/" title="Página oficial de WMarkDown." target="_blank">WMarkDown</a>

https://wmarkdown.k3y.pw/" title="Página oficial de WMarkDown." target="_blank">WMarkDown

                    
  • Language md
  • Lines 1
  • Characters 68
[WMarkDown][https://wmarkdown.k3y.pw/ Página oficial de WMarkDown.]

                    
  • Language html
  • Lines 1
  • Characters 115
<a href="https://wmarkdown.k3y.pw/" title="Página oficial de WMarkDown." target="_blank">WMarkDown</a>

https://wmarkdown.k3y.pw/" title="Página oficial de WMarkDown." target="_blank">WMarkDown

También se pueden hacer Links dentro del mismo sitio Web a partir de enlaces absolutos o relativos haciendo uso de los corchetes o usando la misma metodología de Links no directos de la tabla anterior, con la diferencia de que si el vínculo es dentro de la misma página, éste se hará sobre la misma, subiendo o bajando el Scroll al destino dado. Un ejemplo de ello puede ser el siguiente:

WMarkDown HTML Resultado

                    
  • Language md
  • Lines 1
  • Characters 19
[/doc/example.html]

                    
  • Language html
  • Lines 1
  • Characters 103
<a href="/doc/example.html" title="/doc/example.html" target="_blank">/doc/example.html</a>

/doc/example.html

                    
  • Language md
  • Lines 1
  • Characters 29
[#FAQ-Preguntas-frecuentes-1]

                    
  • Language html
  • Lines 1
  • Characters 133
<a href="#FAQ-Preguntas-frecuentes-1" title="#FAQ-Preguntas-frecuentes-1" target="_blank">#FAQ-Preguntas-frecuentes-1</a>

#FAQ-Preguntas-frecuentes-1

Finalmente, existe otro tipo de Link, el cual llamamos "referenciado", que de por sí se crea en HTML como un vínculo como cualquiera de los anteriores, sea un Link válido o no, y luego, en el entorno cliente, el vínculo cambia según la referencia, si es que ésta existe. La referencia es una línea en la cual se hace un Alias que luego puede ser usado para identificar ese Link, de esa forma, a partir de un nombre o un texto, éste puede ser identificado. A continuación se establece un ejemplo:

WMarkDown Resultado

                    
  • Language md
  • Lines 9
  • Characters 207
- [WMarkDown](https://wmarkdown.k3y.pw/) - [URfree](https://ur3.k3y.pw/) - [Git de inoro](git_inoro) - [Git de KyMAN](git_kyman) [git_inoro]: https://git.a3do.net/ [git_kyman]: https://git.k3y.pw/

Por KyMAN. Creado a fecha 2021/05/16. Última modificación a fecha 2021/05/16.

Códigos de bloque

Los bloques de código o Code Blocks son bloques reservados para código, el cual puede ser visible, como cuando se muestra un fragmento de código para representar un ejemplo o una idea; o para representar algo que es interpretable, como sucede con los diagramas del "mermaid JS". Estos elementos están sujetos a muchos cambios o condiciones por lo que existen multitud de formas de ser llamados, pero todos coinciden en que tengan un inicio y un fin para encapsular el código que se quiere representar. Un par de ejemplos de ambos tipos, tantos de muestreo de código como de interpretación, pueden ser los siguientes:

Tipo WMarkDown Resultado
Muestreo

                    
  • Language md
  • Lines 3
  • Characters 50
```js console.log("Muestra este Script JS"); ```

                    
  • Language js
  • Lines 1
  • Characters 38
console.log("Muestra este Script JS");

Interpretación

                    
  • Language md
  • Lines 4
  • Characters 65
```mermaid graph LR A["Elemento A"] --> B["Elemento B"] ```

                    
  • Language mermaid
  • Lines 2
  • Characters 48
graph LR A["Elemento A"] --> B["Elemento B"]

Como podemos ver en estos ejemplos, se mostró un bloque de código de un bloque de código en la columna de WMarkDown, eso se llevó a cabo haciendo uso de dos delimitadores diferentes, haciendo una anidación de bloques con distintos cierres. Un ejemplo de anidamiento para hacer un muestreo de un muestro lo vemos a continuación:

WMarkDown Resultado

                    
  • Language md
  • Lines 5
  • Characters 62
---md ```js console.log("Muestra este Script JS"); ``` ---

                    
  • Language md
  • Lines 3
  • Characters 50
```js console.log("Muestra este Script JS"); ```

Estos delimitadores diferentes pueden ser cualquiera de los siguientes:

  • ```
  • '''
  • """
  • ---

A éstos les podemos sumar la facultad de poder crear por cada uno, otro nuevo delimitador separando sus elementos con espacios.

La existencia de más de un delimitador también viene por el hecho de que los lenguajes de programación pueden hacer uso de estructuras que puedan solapar este tipo de marcas de texto, como es el caso de Python con los String UTF8, que impide el uso de los códigos de bloque de triple comilla doble.

NOTA: MarkDown tiene un Bug con los bloques de código a la hora de ser usados dentro de celdas de una tabla. En WMarkDown está corregido y se puede hacer uso de elementos HTML sin ningún problema.
Por KyMAN. Creado a fecha 2021/05/15. Última modificación a fecha 2021/05/19.

Parámetros customizados

Los parámetros customizados son parámetros que se identifican mediante una encapsulación de doble corchete, siguiendo la idea de encapsulación de parámetros preprogramados de MediaWiki. Dichos parámetros dan nuevas funcionalidades al entorno del WMarkDown las cuales nombraremos a continuación.

IMPORTANTE: Aunque sintácticamente sean iguales, e incluso se consideren Parámetros Customizados, las inclusiones y los elementos multimedia no están integrados dentro del fichero de Parámetros Customizados, considerados como otros módulos con la misma sintaxis. Es importante tener esto en cuenta por el hecho de que han de estar ordenados según prioridad para evitar la solapación en la configuración.

post_data

El "post_data" es un parámetro que se usa para establecer una información previa de un fichero, aunque también puede ser para un artículo o fragmento de un artículo, aunque por el resultado lo aconsejamos únicamente para encabezar un fichero que en sí sea un artículo completo. Básicamente da la información de los participantes del fichero como autores del mismo, la fecha de creación y la última fecha de modificación, los cuales se identifican dentro de un JSON con las siguientes llaves de diccionario:

  • author: Autor/es y participantes del artículo o fichero.
  • since: Fecha de creación.
  • version: Última fecha de modificación.
No se usan las fechas de los metadatos de los ficheros por el hecho de que dependen del OS y éstos pueden ir condicionados a la creación por descarga al ser un recurso compartido con Git, entre otras cosas.

Las fechas tendrán el formato "YYYYMMDD", donde "YYYY" es el año con cuatro dígitos; el "MM" es el número del mes con 2 dígitos obligatorios; y "DD" que es el día del mes con dos dígitos oblitagorios.

En caso de que no se halla especificado el "author", éste se pondrá como desconocido ("Unknown" o el especificado en la configuración); por otro lado, si no se le especifica el "since" éste será substituído por la fecha de compilación del HTML; y finalmente, si no se le especifica el "version", éste será substituído por el "since".

Como conclusión, podemos exponer que ningún parámetro es obligatorio.

Un ejemplo de éste podría ser el siguiente:

                    
  • Language md
  • Lines 5
  • Characters 94
[[post_data { "author" : "KyMAN", "since" : 20210511, "version" : 20210513 }]]

Este componente personalizado se suele poner al principio del documento, encima del título que encabeza el mismo.

html_data

El HTML data es un parámetro que consta de un diccionario JSON que contiene las variables que se le especifiquen al HTML de compilación donde se integrará la información. Esto permite tener en cada página HTML generada, su SEO META configurado de forma sencilla y customizada. Dichos parámetros pueden variar según el HTML utilizado al gusto del desarrollador o usuario que gestione la documentación o página o páginas Web.

Este complemento no tendrá visualización alguna sobre el HTML final.

Un ejemplo de este componente podría ser el siguiente:

                    
  • Language md
  • Lines 11
  • Characters 529
[[html_data { "title" : "WMarkDown - Parámetros customizados", "url" : "https://wmarkdown.k3y.pw/doc/modules/custom_parameters.html", "author" : "Tarsier, KyMAN", "since" : 20210515, "version" : 20210515, "key_words" : "Whalers,MarkDown,MediaWiki,WMarkDown,módulo,parámetros,custom,personalizado,include,inclusión,import,importación", "description" : "ÇMódulo de parámetros customizados.", "project" : "WMarkDown", "logo" : "https://wmarkdown.k3y.pw/images/wmarkdown.png" }]]

Dicho componente se suele poner al final del documento, aunque puede ser puesto en cualquier otra parte del mismo.

IMPORTANTE: Cualquier llave de parámetro sobreescribirá a los originales, por ejemplo, por defecto los títulos se conforman con le nombre del proyecto y el texto de la primera cabecera dada por el fichero. En el ejemplo expuesto, se subsituye el título por el dado específicamente en este parámetro customizado.
include

El parámetro customizado "include" permite incluír un fichero externo el cual se compilará y se pondrá al nivel de cabeceras actual si no se le especifica previamente a partir del parámetro customizado "header_level" (Ver en el siguiente punto). Pueden existir anidamientos de elementos includos, por lo cual hay que prestar especial atención a aquellos anidamientos que puedan ser recursivos infinitamente. Un ejemplo de inclusión puede ser el siguiente:

                    
  • Language md
  • Lines 24
  • Characters 595
Estamos a nivel 0 de cabecera, por tanto, a la siguiente inclusión no se le añadirá ningún nivel a las cabeceras. [[include PATH1]] # Nivel 1 Estamos en el nivel 1 y a la siguiente inclusión se le añadirá un nivel más a cada cebecera que contenga. [[include PATH2]] Ahora estamos en el nivel de la última cabecera que teníamos en el PATH2, y será el nivel que se le sumará a cada cabecera de la siguiente inclusión. [[include PATH3]] # Nivel 1 Volvimos al nivel 1, por tanto, solo se le sumará un nivel a la siguiente inclusión. [[include PATH4]]
header_level

Este parámetro customizado permite cambiar el nivel de cabeceras con el que se está trabajando, permitiendo, a partir de dicho punto, cambiar el nivel de las mismas según el valor que se le establezca. Éste tiene dos formas de establecerse:

  • A partir de un valor numérico entero sin signo, el cual establece al nivel al cual se irá directamente, siendo 0 el más bajo.
  • A partir de un valor numérico entero con signo más para añadir sobre el nivel actual, o menos para reducir sobre el nivel actual.
Inclusión heredada

La inclusión heredada es la que se explica en el apartado del parámetro customizado "include", donde vemos en el ejemplo que los niveles de las cabeceras aumentan automáticamente según hereden del nivel donde se encuentren. No hace falta especificar nivel de forma forzada mediante "header_level".

Inclusión forzada

La inclusión forzada hace referencia a que se le da un valor numérico entero sin signo, que representa el nivel íntegro al que se quiere mover todo, independientemente de la herencia, por ejemplo:

                    
  • Language md
  • Lines 13
  • Characters 309
## Nivel 2 Estamos en el nivel 2 de herencia, y queremos incluir un fichero en el nivel 4 de forma forzada. Para ello lo haremos de la siguiente forma: [[header_level 4]] [[include PATH1]] Para volver al nivel 2 de nuevo simplemente hemos de establecer aquí lo siguiente: [[header_level 2]]

Como podemos ver en el ejemplo, este parámetro customizado nos permite forzar la inclusión de un fichero en un nivel concreto y luego volver a otro nivel, en el caso del ejemplo, al nivel 2 que era de donde partía.

Inclusión añadida

La inclusión añadida permite desplazar el nivel de las cabeceras X niveles a partir de encabezar el nivel con el signo "+" para añadir o el signo "-" para disminuir. Por ejemplo:

                    
  • Language md
  • Lines 14
  • Characters 509
## Nivel 2 Nos encontramos en el nivel 2. Como este fichero puede ser includo y heredado de otros niveles y queremos reducir 2 niveles para volver al nivel 0 de este fichero para la inclusión del siguiente fichero podemos hacerlo así: [[header_level -2]] [[include PATH1]] Sin embargo, si queremos recuperar la posición anterior no vamos a poder posiblemente pues si ponemos +2, será que aumenta 2 posiciones a partir de la última cabecera del PATH1. Es muy importante tenerlo encuenta.
data_dictionary

El parámetro customizado "data_dictionary" nos permite crear un diccionario de conceptos contra palabras o estructuras de texto que puedan aparecer en la documentación y con ello, generar una definición de las mismas, ya sea como referencia donde se coloque el diccionario; o por el texto, creando un pequeño elemento HTML que hace que cuando el usuario ponga el puntero encima de la palabra o palabras en cuestión, despliegue una pequeña capa con una descripción y vinculación de las fuentes o referencias, ya sea para contrastar como para adquirir más información.

Este elemento se tratará en HTML como un INPUT HIDDEN, el cual será interpretado a nivel cliente sobre JavaScript y generará tanto el diccionario con su buscador, como le dará la función de mostrar definición y fuentes a los elementos en la documentación en general.

Este parámetro customizado se mezclará con otros "data_dictionary" que puedan existir en la documentación por lo que se desaconseja encarecidamente el uso de más de uno de estos elementos, aunque no por ello esté prohibido su uso, permitiendo incluso actualizar los datos de diccionario que ya halla.

Un ejemplo de funcionamiento podría ser el siguiente:

                    
  • Language md
  • Lines 52
  • Characters 1822
## Diccionario [[data_dictionary { "dictionary" : [{ "pattern" : "/\\bky ?man\\b/i", "result" : "KyMAN", "description" : [ "Programador. Trabaja los lenguajes Python, PHP, JavaScript, CSS (CSS y SCSS), SQL ", "(SQLite, MySQL (MariaDB) y SQL Server)" ], "links" : [ "https://git.k3y.pw/KyMAN/", "https://git.a3do.net/KyMAN/", "https://www.youtube.com/channel/UCCAWOt-AxTyAiFWBgyb3X9Q" ] }, { "pattern" : "/\\bmark ?down\\b/i", "result" : "MarkDown", "description" : [ "Simple lenguaje de marcas de texto para documentar. se suele usar en proyectos Git." ], "links" : [ "https://es.wikipedia.org/wiki/Markdown", "https://markdown.es/" ] }, { "pattern" : "/\\bmedia ?wiki\\b/i", "result" : "MediaWiki", "description" : [ "CMS PHP muy extendido para gestionar información y documentación con un pequeño ", "lenguaje de marcas de texto para su procesamiento. Como referencias tendríamos ", "Wikipedia, HiddenWiki, etc." ], "links" : [ "https://www.mediawiki.org/", "https://es.wikipedia.org/wiki/MediaWiki" ] }, { "pattern" : ["/\\bwmarkdown\\b/i", "/\\bwmd\\b/i"], "result" : ["WMarkDown", "WMD"], "description" : [ "Pequeño sistema para documentación de proyectos que mezcla los lenguajes de marcas ", "de texto MarkDown y MediaWiki con HTML y texto plano." ], "links" : [ "https://wmarkdown.k3y.pw/", "https://git.k3y.pw/Whalers/WMarkDown" ] }] }]]

Como podemos ver en el ejemplo, este parámetro es un diccionario JSON con una única entrada, "dictionary", la cual contendrá un Array de diccionarios los cuales tienen los siguientes elementos:

  • pattern: Patrón o patrones de búsqueda.
  • result: Resultado o resultados contra el o los patrones.
  • description: Descripción o definición.
  • links: Referencias o fuentes mediante URL.

Los patrones y los resultados han de tener el mismo número de elementos, es decir, si se le dan 2 patrones de búsqueda ha de haber 2 resultados, pues el sistema entiende que cada patrón es para una posible forma de llamar al elemento diferente. Los resultados permiten, en conjunto con el patrón, corregir posibles errores de escritura de cualquier texto que se le dé a partir del patrón regular.

Con respecto a las imágenes que representan el o los links que puedan estar representadas por defecto en las capas que aparecen para definir un texto cuando le puntero se le pone encima están definidas en SCSS a partir del atributo "data-site" que contiene cada Link, usando la raíz de la página para establecer una imagen icónica del sitio Web al que se le hace referencia.

IMPORTANTE: Se desaconseja el uso de este parámetro por dos motivos: el primero es la limitación de PHP cara la limitación del número de caracteres que tiene a la hora de procesar dicho String en un patrón regular; y la segunda es que actualmente hay una alternativa a dicho sistema que viene siendo en JS la cual implementaría el diccionario desde JavaScript, en el propio constructor del objeto WMarkDown. La solución puesta solventa muchos problemas de esta versión, sin embargo, quita posicionamiento SEO al ser contenido dinámico autogenerado en el cliente y no gestionado mediante Tags, pero por renta cuenta mejor el uso de dicha solución.
Multimedia

Es un Parámetro Customizado que nos permite incluir elementos Multimedia a partir de varios nombres los cuales son: "image", "images", "audio", "audios", "video", "videos" y "embed". Por la complejidad y el tamaño de los Scripts para gestionar dichos elementos, éstos pertenecen a otro fichero como un módulo independiente, con su patrón de búsqueda, sin embargo, se considerarán Parámetros Customizados. Para más información, ir a la sección Multimedia donde se hablará de todo este Parámetro Customizado como si fuera un módulo independiente por la extensión que supone.

Se planea también agregar un nuevo sistema llamado Slider con nombre "slider" que permite la creación de un Slider de cualquiera de los elementos que pertenecen a la multimedia.
wdictionaries

El WDictionaries es como el data_dictionary pero con la diferencia de que coge los diccionarios de forma remota a partir de la siguiente estructura:

                    
  • Language md
  • Lines 5
  • Characters 163
[[header_level 0]] <!-- [[wdictionaries "CABECERA" URLs]] --> [[wdictionaries "Diccionario de prueba" https://wdictionaries.k3y.pw/?es/common,digital]]

En este caso tenemos el nombre de cabecera que queramos ponerle al buscador de términos del diccionario, donde en el HTML comentado llamamos "CABECERA"; a continuación tenemos los enlaces separados entre sí por espacios, tabulaciones, saltos de línea y/o retornos de carro.

IMPORTANTE: El WDictionaries es un proyecto externo al WMarkDown, aunque éste naciera principalmente para el uso dentro del WMarkDown, éste tiene su Web donde se explica su funcionamiento e implementación. Además, el WMarkDown a nivel de JS puede implementar dichos diccionarios sin que se use un WMD, eliminando el fallo a la hora de representar más de un diccionario dentro de estos ficheros.

A continuación ponemos un ejemplo de carga de más de un fichero, por ejemplo, de diversos ficheros JSON para hacer uso de la caché OnLine y del navegador.

                    
  • Language md
  • Lines 8
  • Characters 229
[[header_level 0]] [[wdictionaries "Diccionario de prueba" https://wdictionaries.k3y.pw/json/es/common.json https://wdictionaries.k3y.pw/json/es/digital.json https://wdictionaries.k3y.pw/json/es/users.json ]]
NOTA: El texto de la cabecera puede ser una única palabra sin comillas o un conjunto de ellas encapsuladas entre comillas.
NOTA: Recomendamos encarecidamente el no utilizar dicho Componente Customizado y usar el existente en el entorno cliente contra el propio constructor del WMarkDown en JS.
wmonitor

El WMonitor es un pequeño subsistema del WMarkDown el cual permite establecer un punto de monitoreo de visualizaciones, visitas, likes/dislikes y comentarios contra el cliente. Es importante destacar que funcionará sobre el entorno cliente aunque éste se establezca en el entorno del WMD. Para implementarlo requerimos de nombrar a este Componente Customizado y a continuación, poner un texto indicativo al cual hace referencia. Dicho texto ha de ser único para cada WMonitor, pudiéndose dar el caso de poder compartir dichos datos con otros puntos, pero se perdería la información real de visualizaciones y likes/dislikes de ambos individualmente y pudiendon llevar a engaño visual de la información. Un ejemplo de implementación sobre una cabecera podría ser el siguiente:

WMarkDown Resultado

                    
  • Language md
  • Lines 10
  • Characters 214
[[post_data { "author" : "KyMAN", "since" : 202106029, "version" : 202106029 }]] # Prueba del WMonitor [[wmonitor prueba_del_wmonitor]] Texto que queramos ponerle al cuerpo de este artículo.

Por KyMAN. Creado a fecha 202106029. Última modificación a fecha 202106029.

Prueba del WMonitor

WMonitor

Texto que queramos ponerle al cuerpo de este artículo.

NOTA: El texto indicativo puede ser una palabra sin comillas o varias encapsuladas entre comillas.
NOTA: Habrá más información acerca de éste en la sección que hable sobre el entorno cliente.

El almacenamiento de los datos en el entorno servidor de este Componente Customizado viene siendo en un archivo SQLite para que el administrador tenga control sobre los distintos ficheros de este tipo, así como su globalización mediante el Driver PDO.

ignore

Este Componente Customizado simplemente hace que WMarkDown ignore lo que tenga dentro, dejándolo sin formatear ni nada. Es importante destacar que el doble cierre de corchete se considerará el cierre del "ignore", y que en caso de necesitar ponerlo es importante hacer uso de HTML. Unos ejemplos de ésto podrían ser los siguientes, donde el primero simplemente hace ignorar una palabra, el siguiente un texto, y en el siguiente un JSON con doble cierre de corchete.

WMarkDown Normal Ignorado

                    
  • Language md
  • Lines 9
  • Characters 184
# Testeando el *ignore* Tengo 35 [[ignore años]]. Fichero: [[ignore vacíos.json]] JSON: [[ignore '["jiji", "jaja", ["cosa.txt", "cosa.json"<span>]</span>]']]

Testeando el ignore

Tengo 25 años.

Fichero: vacíos.json

JSON: '["jiji", "jaja", "cosa.json"]'

Testeando el ignore

Tengo 35 años.

Fichero: vacíos.json

JSON: '["jiji", "jaja", ["cosa.txt", "cosa.json"]]'

NOTA: SPAN en HTML no es más que una etiqueta de línea, visualmente no se ve ni se percibe, y gracias a ésta podremos escapar caracteres que puedan ser problemáticos en última instancia, como éste que acabamos de ver.

El _links_group_ o "Grupo de Links" viene siendo pequeño componente que permite mostrar un conjunto de Links sin mostrar sus URIs, sino una imagen representativa y a lo sumo, un pequeño texto o palabra acorde a éste, iconificando los enlaces mediante imágenes, siguiendo la estructura del módulo Multimedia, y automatizando ciertas cosas como la carga y selección de imágenes funcionales, organizamiento de los mismos y los estilos básicos. Su orden se basa en el orden dado en el Array JSON el cual define este Componente Customizado, e irántodos en la misma línea, centrados, y cuando hay tantos que exceden la línea automáticamente crearán una segunda, tercera o tantas líneas como requieran para mostrar todos los Links.

La estructura del JSON no es más que un Array de diccionarios, donde cada diccionario no es más que un Link y el cual posee la siguiente estructura:

  • images (required): Array de URLs de imágenes alternativas, en el orden de prioridad.
  • link (required): URL a la que se quiere enviar.
  • text (required): Texto que acompaña a la imagen.
  • self (optional): Indica si se abre en la pestaña/ventana actual (true) o se abre una nueva (false).

Con respecto al campo "images", se pueden poner tantas URLs como se quieran, incluyendo repetidas, aunque la idea de repetidas en una mala idea porque pasará exactamente lo mismo en los casos repetidos; y se cogerán partiendo de la primera imagen hasta la última, donde la primera imagen que encuentre que no de error, será la que ponga. En caso de que todas las opciones den error o que no se establezca imagen, la imagen quedará vacía.

Un ejemplo de funcionamiento puede ser el siguiente:

WMarkDown Resultado

                    
  • Language md
  • Lines 29
  • Characters 885
# Links de ejemplo [[links_group [{ "images" : ["https://wmarkdown.k3y.pw/images/wmarkdown.png"], "link" : "https://wmarkdown.k3y.pw/", "text" : "WMarkDown" }, { "images" : ["https://git.k3y.pw/assets/logo-d36b5212042cebc89b96df4bf6ac24e43db316143e89926c0db839ff694d2de4.svg"], "link" : "https://git.k3y.pw/", "text" : "Git" }, { "images" : ["https://gittutorials.k3y.pw/images/gittutorials.png"], "link" : "https://gittutorials.k3y.pw/", "text" : "GitTutorials" }, { "images" : [], "link" : "https://wdictionaries.k3y.pw/", "text" : "WDictionaries" }, { "images" : ["https://kyman.local/images/logo.png"], "link" : "https://kyman.k3y.pw/", "text" : "KyMAN Wlog" }, { "images" : ["https://kanvas.k3y.pw/images/kanvas.png"], "link" : "https://kanvas.k3y.pw/", "text" : "Kanvas" }] ]]

Links de ejemplo

icon

Este Componente Customizado sirve para marcar algo como una nota, alerta, aviso, etc. Y suele ser usado para los Quotes (Componente que se verá más adelante). Dicho Componente Customizado puede ser nombrado como:

  • icon
  • i
  • !
NOTA: Las nomenclaturas "i" y "!" están hechas para agilizar y facilitar su uso.

La sintaxis de los iconos es la siguiente, donde podemos ver las siguientes partes:

                    
  • Language md
  • Lines 1
  • Characters 24
[[icon|i|! TIPO TEXTO?]]
  • TIPO: Es el tipo de icono que se quiere mostrar. Dicho nombre lo podemos sacar del fichero de iconos de CSS y nos valdría cualquiera de ellos, aunque oficialmente existen 5: note o notas; alert o alertas; important o cosas importantes; warning o avisos; y danger o peligro.
  • TEXTO: Es un campo opcional que permite añadirle un texto que lo acompañe.
NOTA: Es importante tener en cuenta que este Componente Customizado es un elemento de línea que puede estar integrado dentro de un texto entre otros.

Los tipos de icono que hay son los siguientes:

Tipo WMarkDown Ejemplo Resultado
Nota

                    
  • Language md
  • Lines 1
  • Characters 15
[[! note NOTA]]

                    
  • Language md
  • Lines 5
  • Characters 80
> [[! note NOTA]]: Esto es una nota. > [[! note]] Esto es una nota.

NOTA: Esto es una nota.
Esto es una nota.

Alerta

                    
  • Language md
  • Lines 1
  • Characters 18
[[! alert ALERTA]]

                    
  • Language md
  • Lines 5
  • Characters 88
> [[! alert ALERTA]]: Esto es una alerta. > [[! alert]] Esto es una alerta.

ALERTA: Esto es una alerta.
Esto es una alerta.

Aviso

                    
  • Language md
  • Lines 2
  • Characters 37
[[! warn AVISO]] [[! warning AVISO]]

                    
  • Language md
  • Lines 5
  • Characters 81
> [[! warn AVISO]]: Esto es un aviso. > [[! warn]] Esto es un aviso.

AVISO: Esto es un aviso.
Esto es un aviso.

Importante

                    
  • Language md
  • Lines 1
  • Characters 26
[[! important IMPORTANTE]]

                    
  • Language md
  • Lines 5
  • Characters 110
> [[! important IMPORTANTE]]: Esto es algo importante. > [[! important]] Esto es algo importante.

IMPORTANTE: Esto es algo importante.
Esto es algo importante.

¡Peligro!

                    
  • Language md
  • Lines 1
  • Characters 20
[[! danger PELIGRO]]

                    
  • Language md
  • Lines 5
  • Characters 99
> [[! danger PELIGRO]]: Esto es algo peligroso. > [[! danger]] Esto es algo peligroso.

PELIGRO: Esto es algo peligroso.
Esto es algo peligroso.

WDoc

El WDoc es un sistema basado en el XDoc para documentar código, pero con la diferencia que en este caso es para documentar el código a partir de ficheros WMD para dejar el código lo más limpio posible, además de agilizar la documentación del código dentro de los documentos WMD, manteniendo una pequeña estructura simplificada de XDoc para una documentación rápida de variables y metodos que nos podamos encontrar. El WDoc se basa en tres partes diferenciadas las cuales son:

  • Descripción: Inicia con cualquier caracter que no sea "@" ni "#". Pequeño texto descriptivo para definir por encima el método o variable que se quiera documentar.
  • Data o información: Inicia con "@". Valores basados en una llave y un valor tanto para el XDoc como para el propio WDoc, y suelen ser elementos comunes.
  • Atributos y retorno: Inicia con "#". Parámetros de entrada del método y retorno del mismo.

Cada elemento conforma una única línea dentro del elemento o bloque WDoc y se distinguen a partir de su inicio el cual se detalla en la lista anterior.

En el caso de la descripción, cualquier línea que empiece sin ninguno de los caracteres determinados será concatenada a la descripción separados por un simple espacio. Permite el uso de HTML, lo mismo que en resto de atributos, aunque en los demás no se aconseja, y se hace uso de HTML si se viere necesario pero en la medida de lo posible y por la descripción de este Componente Customizado no se aconseja hacer un uso excesivo de ello.

El en el caso de Data o información, sirve para cumplimentar datos genéricos del XDoc o WDoc, siendo algunos de ellos los siguientes:

  • name (required): Sería el nombre completo del elemento, es decir, si se encuentra en una clase, subclase o espacio de nombres, ha de representar se entero, sin espacios.
  • language (required): Lenguaje de programación en el que esté trabajado sin espacios.
  • author (optional): Autor o autores del elemento a documentar, separados por comas y sin espacios.
  • since (optional): Fecha en formato "YYYYMMDD" desde la primera aparición en código de dicho elemento.
  • version (optional): Última fecha de modificación en formato "YYYYMMDD" de dicho elemento.
  • deprecated (optional): Determina si está obsoleto o no. Su valor ha de ser "true".
IMPORTANTE: Los elementos de Data o información "required" u obligatorios deben de existir siempre o pueden dar resultados no esperados por el redactor.

Finalmente, en el caso de los atributos se determinan a partir de 4 puntos los cuales se separan con espacios, siendo el último el único capaz de contener dichos espacios. La separación entre ellos pueden ser espacios o tabulaciones, y pueden ser tantos como se desee para mantener una legibilidad a la hora de representar en código. Dichos elementos de los que consta son los siguientes:

  • nombre (required): Nombre del atributo.
  • tipados (required): Tipado o posibles tipados del atributo. En caso de poder ser cualquiera se pondría la palabra "ANY" para representar "cualquiera" (Por defecto, el tipado "-" será "ANY").
  • modo (required): Determina si el atributo es obligatorio (Required) u opcional (Optional).
  • descripción (optional): Pequeña descripción del atributo.
NOTA: Para representar el retorno, hemos de usar el nombre de atributo return, que siguiendo con el modelo de un atributo continuaría con el tipado o tipados de variable de retorno, un guión ("-") por el hecho de no ser ni opcional, ni requerido ni ninguna otra forma dependiente del usuario, y con una pequeña descripción opcional que determine qué es lo que retorna.

Un ejemplo de dicho sistema puede ser el siguiente:

                    
  • Language md
  • Lines 13
  • Characters 419
Descripción WDoc del método **AnP.string_variables**. [[wdoc Procesa las variables de un String. @name AnP.string_variables @lang Python #string str required String a procesar. #variables dict,list,tuple optional Variables para procesar el String. #default str optional Valor por defecto. #return str - String procesado. ]]

Su resultado vendría siendo el siguiente:

Descripción WDoc del método AnP.string_variables.

AnP.string_variablesPython

Procesa las variables de un String.

strAnP.string_variablesstringstrrequiredString a procesar.variablesdictlisttupleoptionalVariables para procesar el String.defaultstroptionalValor por defecto.returnstrString procesado.
stringstrrequiredString a procesar.variablesdictlisttupleoptionalVariables para procesar el String.defaultstroptionalValor por defecto.returnstrString procesado.
  • nameAnP.string_variables
  • languagePython

También se cuenta con posibles sobrecargas, es decir, que un método pueda tener más de un tipo de entrada con lo que éste actuará diferente en base a su entrada. Como éste se basa en los atributos y retorno del mismo, se puede poner el parámetro "@overload" sin ningún valor ni nada, lo que indica que a partir de ahí empieza una sobrecarga del método con sus propios parámetros de entrada y retorno.

NOTA: Un retorno vacío se especificará automáticamente con el tipado "void", por lo que no haría falta ni definirlo.
NOTA: Es importante determinar que en lenguajes como Python, en sus métodos objeto o métodos de clase, el primer parámetro de entrada se entiende como un parámetro forzado del propio lenguaje por el cual no se determinará en el WDoc, dando a entender que en estos casos se empezará en el segundo parámetro de entrada por ser un parámetro dado al usuario, que será con los que pueda interactuar.
plain

El Componente Customizado "plain" nos permite establecer un fragmento de texto totalmente plano a nivel de HTML, sin que éste se procese ni se etiquete. Es muy útil para mantener estructuras en los títulos u otros elementos vinculados. Un ejemplo de funcionamiento puede ser el siguiente:

                    
  • Language md
  • Lines 9
  • Characters 164
# [[AnP.get_dictionary_path]] Título del bloque "AnP.get\_dictionary\_path". # AnP.get_dictionary_path Título del bloque "AnP.get\_dictionary\_path".
NOTA: Los textos que queden planos quedarán siendo parte de su padre y no distinguiéndose del resto de los textos puesto que no estarán etiquetados.
Por KyMAN. Creado a fecha 2021/05/18. Última modificación a fecha 2021/05/25.

Multimedia

Los elementos Multimedia son aquellos elementos como el Audio, Imágenes, Vídeos, etc. Incluso incrustaciones como los propios PDF o librerías que interpretan cosas como ThreeJS contra elementos 3D. En este caso, y por la imposibilidad por la carga de trabajo que ésto supone, se expondrán ciertas integraciones contra WMarkDown para poder trabajar de forma sencilla algunos elementos, el resto han de ser tratados directamente sobre HTML, CSS y JS. Es importante tener en cuenta que este módulo es un Parámetro Customizado, que aunque halla sido externalizado por extensión del mismo de "custom_parameters", éste no deja de trabajar con la misma estructura sintáctica, es por lo que se sigue considerando un Parámetro Customizado.

Éste módulo se amplía en JavaScript por el hecho del Lazying, que de forma nativa, en los componentes HTML existe para IMG, AUDIO y VIDEO pero no es un estándar para todos los navegadores por lo que la falta de compatibilidad dio lugar a la creación de un fragmento de código JS para gestionar el Lazy. Para compatibilizar con SEO sobre etiquetados HTML se hace uso de la etiqueta NOSCRIPT, donde se pondrá en formato HTML todos los elementos sin Lazying, de esta forma, cuando un indexador busque por el código HTML, éste no podrá ejecutar JS para acceder a los resultados finales ni interpretar el parámetro "data-src" utilizado para poner las URL; sin embargo, sí sería capaz de intepretar como HTML el contenido del NOSCRIPT al ser un entorno que no tiene habilitada la ejecución de Scripts.

Como parte común para todas las operaciones que tenemos con el módulo Multimedia tenemos la sintaxis de llamada, que viene siendo como un Componente Customizado usando la encapsulación con dobles corchetes; a continuación el nombre del componente multimedia que queramos representar, incluyendo su nombre de conjunto; y finalmente los datos de fuentes y textos que requiramos para dicho elemento multimedia. A continuación marcamos una estructura de como se pondría:

                    
  • Language md
  • Lines 5
  • Characters 66
# Estructura de elementos Multimedia [[COMPONENTE FUENTES]]

Cada elemento multimedia, a excepción de los Links embedados como Youtube, Soundcloud, etc. Pueden tener más de una fuente opcional para que en caso de que caiga una de ellas pueda cargarse otra, y pueden meterse tantas fuentes opcionales como se desee. Para llevar a cabo dicha tarea se usa un Script JS que se adjunta a las librerías JS de WMarkDown la cual va cargando mediante Lazying los elementos, y durante la carga, analiza de forma ordenada, desde el primero hasta el último, buscando el primer Link que esté disponible para el recurso, el cual será el que use para mostrar el contenido. En caso de no encontrarse ninguna opción, se dejará en blanco. Un ejemplo de esta mecánica podría ser el siguiente:

WMarkDown Resultado

                    
  • Language md
  • Lines 12
  • Characters 522
# Ejemplo de carga opcional [[image [ "https://dictionary.cambridge.org/es/images/thumb/cog_noun_002_07459.jpg", "https://upload.wikimedia.org/wikipedia/commons/9/92/Cog_font_awesome.svg", "https://cdn.icon-icons.com/icons2/2066/PNG/512/cog_icon_125323.png", "https://cdn.pixabay.com/photo/2013/07/12/18/19/cog-153268_960_720.png", "https://cdn.icon-icons.com/icons2/1875/PNG/512/cog_120288.png", "https://cdn.icon-icons.com/icons2/2066/PNG/512/cog_icon_125323.png" ] Configuración]]

Configuración Configuración

En el Array de URLs de imagen cogerá la primera URL en el orden en el que se encuentran en el mismo Array, que retorne una imagen correctamente, de esta forma, si falla la primera irá a la segunda, si falla la segunda irá a la tercera, y así sucesivamente.

Con respecto al SEO es importante destacar que al ser un Script el cual gestiona qué URL mostrar, se le impide al SEO detectar dicha imagen, por lo que se hace uso de la etiqueta NOSCRIPT de HTML que permite meterle contenido String y el cual será interpretado por navegadores o entornos donde no se pueda ejecutar Scripts, como pueden ser los Metabuscadores o los indexadores, pero si los Scripts están habilitados, esta etiqueta será ignorada y no se mostrará al usuario, por lo que dicha etiqueta tendrá los objetos de cada uno de los recursos opcionales dados, permitiendo al SEO ganar puntos de posicionamiento aún a pesar de ser un sistema dinámico basado en Scripts clientes.

Ejemplo del NOSCRIPT para el SEO. Ejemplo del NOSCRIPT para el SEO.

Los textos que acompañan a los elementos multimedia son textos opcionales y no requieren de encapsularse entre comillas pues se detecta como Link hasta donde halla una separación, tabulación o salto de línea.

Imágenes

Las imágenes son el elemento más sencillo y pueden ser tratadas de forma independiente o de forma conjunta. La idea es poder poner una imagen en formato de bloque en HTML, es decir, que sea independiente al resto del texto; o un conjunto de imágenes que pase lo mismo pero quedando todo en un único bloque con imágenes más pequeñas visualmente.

Para llevar a cabo dicha operación usaremos usaremos el nombre de componente image para una única imagen que ocupe casi todo el ancho; o bien images para un Grid de imágenes sucesivas. Cada imagen vinculará consigo misma.

En la presentación del módulo Multimedia tenemos un ejemplo de muestreo de una imagen con 6 links opcionales, donde podemos apreciar la siguiente estructura:

                    
  • Language md
  • Lines 11
  • Characters 149
[[image SOURCES TEXTO?]] [[images SOURCES_1 TEXTO_1? SOURCES_2 TEXTO_2? SOURCES_3 TEXTO_3? ... SOURCES_N TEXTO_N? ]]
  • SOURCES (required): Array de Links de imágenes alternativas. Puede estar vacío, tener una o más fuentes.
  • TEXTO (optional): Texto que acompaña a la imagen.

A continuación se exponen varios ejemplos de imagen única:

Descripción WMarkDown Resultado
Imagen con un único Link.

                    
  • Language md
  • Lines 3
  • Characters 45
[[image https://i.imgur.com/YueKYv4.png]]

Imagen con un único Link acompañada de una texto.

                    
  • Language md
  • Lines 3
  • Characters 80
[[image https://i.imgur.com/bAlLssr.png Aprendiendo a programar en Java...]]

Aprendiendo a programar en Java... Aprendiendo a programar en Java...

Imagen con 6 Links alternativos de un icono de configuración con su texto de configuración.

                    
  • Language md
  • Lines 10
  • Characters 491
[[image [ "https://dictionary.cambridge.org/es/images/thumb/cog_noun_002_07459.jpg", "https://upload.wikimedia.org/wikipedia/commons/9/92/Cog_font_awesome.svg", "https://cdn.icon-icons.com/icons2/2066/PNG/512/cog_icon_125323.png", "https://cdn.pixabay.com/photo/2013/07/12/18/19/cog-153268_960_720.png", "https://cdn.icon-icons.com/icons2/1875/PNG/512/cog_120288.png", "https://cdn.icon-icons.com/icons2/2066/PNG/512/cog_icon_125323.png" ] Configuración]]

Configuración Configuración

Imagen GIF con 3 links opcionales, acompañada de texto.

                    
  • Language md
  • Lines 7
  • Characters 217
[[image [ "https://i.imgur.com/xL3UgP6.gif", "http://i.redd.it/ibw4tcsb00wx.gif", "http://moviecitynews.com/wp-content/uploads/2013/06/Steven-Seagal-dancing.gif" ] Steven Seagal bailando en Rusia]]

Steven Seagal bailando en Rusia Steven Seagal bailando en Rusia

Por otro lado, para representar más de una imagen hemos de seguir el mismo procedimiento anterior pero nombrando images en vez de images, y por cada línea se entenderá como una imagen independiente a la anterior.

Descripción WMarkDown Resultado
Ejemplo de múltiples imágenes, donde la primera tiene un Link secundario, cada uno con sus textos.

                    
  • Language md
  • Lines 7
  • Characters 349
[[images ["https://i.ytimg.com/vi/J-YXLy9Lc7Y/maxresdefault.jpg", "https://images-na.ssl-images-amazon.com/images/I/61nwQasys5L._SY355_.jpg"] Classixx NYC https://images-na.ssl-images-amazon.com/images/I/61nwQasys5L._SY355_.jpg Classixx, sesión de Youtube. https://i.ytimg.com/vi/BeuWg4jdYaY/maxresdefault.jpg Classixx mixmag ]]

Classixx NYC Classixx NYC Classixx, sesión de Youtube. Classixx, sesión de Youtube. Classixx mixmag Classixx mixmag

Vídeos

Los vídeos tienen la misma sintaxis que las imágenes con la diferencia de que éstos tienen a mayores, opcionalmente, un segundo link o conjunto de Links que viene siendo el Poster o carátula a mostrar mientras no se reproduzca el vídeo. Básicamente puede tener las dos siguientes estructuras:

                    
  • Language md
  • Lines 11
  • Characters 197
[[video SOURCES POSTER? TEXTO?]] [[videos SOURCES_1 POSTER_1? TEXTO_1? SOURCES_2 POSTER_2? TEXTO_2? SOURCES_3 POSTER_3? TEXTO_3? ... SOURCES_N POSTER_N? TEXTO_N? ]]

Cada campo indica lo siguiente:

  • SOURCES (required): Link o Links fuente del vídeo.
  • POSTER (optional): Link o Links fuente de la imagen que hace de poster.
  • TEXTO (optional): Texto que acompaña al vídeo.

Como con el caso de las imágenes, la carga de los elementos de vídeo se hacen mediante Lazying para evitar un consumo excesivo del ancho de banda. A continuación se exponen unos cuantos ejemplos, uno por cada caso principal que pueda salir.

Audios
Embeds
Por KyMAN. Creado a fecha 2021/05/16. Última modificación a fecha 2021/05/16.

Quotes

Los Quotes o comentarios son bloques de texto que se destacan un poco de los demás para indicar anotaciones, avisos, y otro tipo de mensajes especiales adjuntos al fragmento donde se encuentran. Para poder hacer uso de este módulo simplemente hemos de usar al principio del párrafo el caracter de cierre de diamante ">", pudiendo usar más de uno para tener mayor tabulación y representar mayor o menor nivel. Dentro de estos párrafos especiales, los módulos y parámetros de línea siguen funcionando igualmente.

WMarkDown Resultado

                    
  • Language md
  • Lines 12
  • Characters 235
# Ejemplo de Quote Este es un párrafo normal. > Este párrafo de aquí es un *Quote*. Sigue las mismas normas que un párrafo normal. Este es otro párrafo normal. >> Este es un *Quote* con mayor tabulación.

Ejemplo de Quote

Este es un párrafo normal.

Este párrafo de aquí es un Quote. Sigue las mismas normas que un párrafo normal.

Este es otro párrafo normal.

Este es un Quote con mayor tabulación.

Los Quotes son muy utilizados para marcar notas o advertencias ayudándose del Componente Customizado "icon", como se hace en los ejemplos del mismo.

Por KyMAN. Creado a fecha 2021/12/04. Última modificación a fecha 2021/12/04.

Tablas

El módulo de las tablas busca agilizar y facilitar la escritura de tablas en WMarkDown, basándose en el sistema de tablas de MediaWiki, pero con algunas diferencias. La sintaxis para crear una tabla en WMarkDown viene siendo con una línea con la que se inicia con la apertura de corchete seguido de un cierre de exclamación, y se entiende como tabla hasta que halla una línea que se inicia con un un cierre de exclamación seguida de un cierre de corchete. Cada línea se entiende como una tupla si ésta se inicia con tubería, sino, será como un comentario dentro de la propia tabla. No existen los saltos de línea.

NOTA: Las tablas de WMarkDown están diseñadas para contenido muy simplificado (Datos, textos muy pequeños, etc.).

Un ejemplo de tabla podría ser lo siguiente:

WMarkDown HTML Resultado

                    
  • Language md
  • Lines 8
  • Characters 303
[! style="width:100%;" Esto es un comentario y se ignorará de la tabla. |^Cabecera|ejemplo1|ejemplo2|ejemplo3|ejemplo4|ejemplo5 |tupla1 |dato1 |dato2 |dato3 |dato4 |dato5 |compacto|dato1|dato2|dato3|dato4|dato5 |colspan|dato1|||dato 2, 3 y 4|dato5 |_pie|||||Esto es el pie de tabla. !]

                    
  • Language html
  • Lines 42
  • Characters 1398
<table style="width"> <thead> <tr> <th>Cabecera</th> <th>ejemplo1</th> <th>ejemplo2</th> <th>ejemplo3</th> <th>ejemplo4</th> <th>ejemplo5</th> </tr> </thead> <tbody> <tr> <td>tupla1</td> <td>dato1</td> <td>dato2</td> <td>dato3</td> <td>dato4</td> <td>dato5</td> </tr> <tr> <td>compacto</td> <td>dato1</td> <td>dato2</td> <td>dato3</td> <td>dato4</td> <td>dato5</td> </tr> <tr> <td>colspan</td> <td>dato1</td> <td colspan="3">dato 2, 3 y 4</td> <td>dato5</td> </tr> </tbody> <tfoot> <tr> <th>pie</th> <th colspan="5">Esto es el pie de tabla.</th> </tr> </tfoot> </table>

Cabeceraejemplo1ejemplo2ejemplo3ejemplo4ejemplo4
tupla1dato1dato2dato3dato4dato5
compactodato1dato2dato3dato4dato5
colspandato1dato 2, 3 y 4dato5
pieEsto es el pie de tabla.

Como podemos ver en el ejemplo anterior, podemos ponerle atributos a la etiqueta HTML en la línea de apertura, y también podemos ver que una línea sin cabecera de tubería también se considera un comentario, que aunque no salga reflejado en el HTML final, sí nos permite hacer breves comentarios de puntos específicos de la propia tabla. También tenemos marcas que identifican si la tupla pertenece a la cabecera, cuerpo o pie de página donde:

  • Si la tupla empieza por "^", "¨" o "-" se considerará cabecera.
  • Si la tupla empieza por "_" se considerará pie.
  • Si la tupla empieza por "#" se considera que será tanto cabecera como pie.
  • Si la tupla empieza por algo distinto se considerará cuerpo.

Cualquiera de estos elementos pueden poner en cualquier punto de la tabla, sin embargo, las cabeceras se unirán, en el orden en el que fueron establecidas, en la THEAD, en la parte superior de la tabla; lo mismo con los pie de tabla pero en la parte inferior, en la etiqueta TFOOT; y los elementos de cuerpo, que se ordenarán en el cuerpo de la misma forma que las cabeceras y los pies, en la etiqueta TBODY.

Cada celda puede contener elementos WMarkDown como enlaces, componentes, etc. Siempre que éstos sólo posean una única línea y no contengan el caracter de la tubería.

Finalmente, estas tablas son capaces de representar COLSPAN, a partir del número de tuberías que precede a la celda, donde si es una se considerará una celda normal de 1 casilla; mientras que si son de más se considerará que ocupan el número de tuberías que la preceden.

NOTA: Un punto interesante de este tipo de tablas es que se ignoran los espacios antes y después del texto de una celda, por lo que permite escribir las tablas con la forma misma de la tabla, dando un índice visual en texto plano WMarkDown muy interesante para ciertas cosas.
IMPORTANTE: Para dejar una celda vacía simplemente hemos de escribir su tubería, y a continuación, un espacio en blanco que la separe de la tubería de la siguiente celda.
Por KyMAN. Creado a fecha 2021/05/12. Última modificación a fecha 2021/05/13.

mermaid JS

La librería mermaid es una pequeña librería JavaScript desarrollada en NodeJS para la creación, a partir de marcas de texto dentro de un String, diagramas y flujos. El Link para la documentación así como descarga y más información sobre el proyecto lo tenemos a continuación.

https://mermaid-js.github.io/

Al ser una librería externa creemos que es mejor vincular con la fuente original para más información, además de así mostrar autoría y la indormación de uso más fiderigna entre otras opciones. Si os gusta por favor, apoyar el proyecto en la medida que podáis, ya sea dándolo a conocer o mediante los medios que los autores presenten.

Para integrar mermaidjs en la documentación jugaremos con la misma sintaxis u estructura de MarkDown, usando un bloque de código donde intgrar nuestro diagrama, con nombre del lenguaje "mermaidjs". Dicha estructura puede adaptarse, según la idea de los bloques de código, con el sistema dado para MediaWiki a partir de la etiqueta HTML source lang, o en adaptación a interpretación JS, pre lang.

WMarkDown Resultado

                    
  • Language txt
  • Lines 4
  • Characters 63
```mermaid graph LR A["Ejemplo A"] --> B["Ejemplo B"] ```

                    
  • Language mermaid
  • Lines 2
  • Characters 46
graph LR A["Ejemplo A"] --> B["Ejemplo B"]

Por KyMAN. Creado a fecha 2021/05/16. Última modificación a fecha 2021/05/16.

Maths

Este tipo de bloque de código está creado para poder mostrar, a partir de un String o texto dado, una fórmula matemática legible. Para llevar a cabo dicha operación se hace uso de la librería MathJax, una librería desarrollada en NodeJS, tanto para navegadores como para proyectos NodeJS, VueJS o derivados, que permite transformar un texto LaTeX, HML, etc. En una fórmula matemática legible, para mostrar operaciones matemáticas entre otras funciones.

Para poder crear una fórmula matemática simplemente hemos de crear un bloque de código con el nombre "maths" y dentro poner la formulación que se quiere visualizar. Automáticamente, WMarkDown lo procesará y le enviará la orden a MathJax.

Ejemplos de funcionamiento podrían ser los siguientes:

WMarkDown Resultado

                    
  • Language md
  • Lines 3
  • Characters 27
```maths x = 2a^4 + 5 ```

                    
  • Language maths
  • Lines 1
  • Characters 12
x = 2a^4 + 5

                    
  • Language md
  • Lines 3
  • Characters 34
```maths y = \sqrt{x^2 + 5n} ```

                    
  • Language maths
  • Lines 1
  • Characters 19
y = \sqrt{x^2 + 5n}

Como esta librería es externa, para más información aconsejo encarecidamente mirar la documentación misma de la librería a partir del siguiente enlace:

http://docs.mathjax.org/en/latest/

Por KyMAN. Creado a fecha 2021/05/02. Última modificación a fecha 2022/04/02.

Bugs

Aquí se documentarán todos los Bugs encontrados hasta la fecha y se determinará si está arreglado o no. También pueden salir en los objetivos de los miembros del proyecto. Los Bugs que aparecen solo serán los reportados o los encontrados por el propio equipo durante el desarrollo, pruebas o funcionamiento del mismo.

La gestión de realización de los Bugs siguer el mismo patrón de los objetivos, donde cada Checkbox es cada uno de los miembros de Whalers: Tarsier y KyMAN consecutivamente.

Hash Alphabet bloqueado por Array

Si estableces un Array de caracteres en el Hash Alphabet, el método WMarkDown::get_hash se bloquea. Con esto también se vio el riesgo que supone permitir cualquier tipo de caracter por lo que para arreglar esta observación es importante generar un limitador de caracteres que puede partir una vez cargadas las configuraciones dejando al parámetro "hash_alphabet" como un parámetro global privado de la configuración ya gestionado.

  • Arreglar el bloqueo por Array del "hash_alphabet".
  • Gestionar de forma global los caracteres del "hash_alphabet".

Formatos sin escapes

Cuando queremos poner un guión bajo u otro caracter usado para formatos de línea, éstos son substituídos, cuando hay un par, por el formato en cuestión. Requieren de un sistema de escape urgente pues están dañando la sintaxis del texto.

- Escapar caracteres de formato y de línea.

Bloque de código no reconocido

Existe un problema a la hora de interpretar un bloque de código, en este caso en el fichero de FAQ, donde hay dos bloques y toma al primero como párrafo, lo que elimina el formato de los bloques siguientes.

- Arreglar el problema de los bloques de código.

El problema estaba en que no seleccionaba el primer bloque, sino el último.

Fallo de escape de estilos

Los escapes de los estilos salen reflejados también en el menú. También fallan los niveles ante la inclusión de ficheros por herencia del último nivel utilizado.

  • Corregir en el menú los escapes de los estilos.
  • Corregir niveles heredados.
Parte de los Bugs se ven por la librería del Syntax Highlighter actual.

Fallo última línea CodeBlocks

A veces desaparece la última línea en los CodeBlocks.

- Encontrar y corregir el Bug.

El problema residía en el Scroll Hidden del elemento padre del bloque de código en SCSS.

Click central imágenes multimedia

Cuando hacemos Click con el botón central del ratón nos da un error en la página que incluso nos llega a salir de la vista actual y en ocasiones, no dejando regresar con el Back.

- Arreglar el botón central de los elementos multimedia.

Anidación listado numérico

Hay un Bug en la anidación de listado numérico cuando éste es con más de un caracter Hash, dando como título dicha línea. Un ejemplo puede ser el siguiente:

                    
  • Language md
  • Lines 10
  • Characters 152
Lista numérica con anidación con Bug: # elemento1. # elemento2. ## Elemento2.1 ## Elemento2.2 ## Elemento2.3 # elemento3. # ... # elementoN.

En este ejemplo, los elementos anidados en el punto 2 serán títulos dentro de una lista que continúa el orden numérico como si no estuvieran anidados, sino que pertenecieran al primer nivel de la lista.

- Arreglar el problema de anidación.

wmd.php no tira a la primera

El archivo "wmd.php" no tira a la primera, es como que requiere de que exista el "html.files.json".

- Arreglar este problema.

Hay un evento que se genera automáticamente con ECMA que determina si se cargó correctamente el logo o no. En caso de no haber sido cargado correctamente, éste desaparecerá. El caso es que no funciona.

Arreglar el Bug.

NOTA: El problema se encontraba en que el evento se generaba una vez se cargaba la página Web, con el problema consiguiente de que ya pudo haber saltado el evento de carga de la imagen y por tanto, no afectar realmente al estado del mismo. Para solucionarlo lo que había que hacer es crear un objeto Image el cual tenga el mismo SRC y aplicarle el evento a éste y los efectos al original.
                    
  • Language js
  • Lines 10
  • Characters 407
const logo = wmarkdown.querySelector(".logo img"), temporary_image = new Image(); logo.setAttribute("data-status", "loading"); temporary_image.src = logo.getAttribute("src"); temporary_image.addEventListener("load", event => logo.parentNode.setAttribute("data-status", "ok")); temporary_image.addEventListener("error", event => logo.parentNode.setAttribute("data-status", "error"));

20221012 - filegetcontents directory

Hay un error en la actual línra 229 del fichero /PHP/WMarkDown.php en la cual se determina que se está intentando hacer una lectura de un directorio como fichero.

                    
  • Language php
  • Lines 6
  • Characters 218
public function load_file($path){ foreach(["", $this->root, $this->wmarkdown_root] as $root) if(file_exists($file = $root . $path)) return file_get_contents($file); return null; }
  • Localizar el problema.
  • Arreglarlo.
                    
  • Language php
  • Lines 6
  • Characters 244
public function load_file($path){ foreach(["", $this->root, $this->wmarkdown_root] as $root) if(file_exists($file = $root . $path) &emp;&emp; !is_dir($file)) return file_get_contents($file); return null; }
Por KyMAN. Creado a fecha 2021/05/02. Última modificación a fecha 2022/04/02.

Objetivos

Aquí se incluirán los objetivos a realizar por los miembros del equipo, los Whalers, y se verán los objetivos que aún faltan por alcanzar, así como todos aquellos objetivos alcanzados.

Tarsier, KyMAN y angelus

Aquí ser pondrán dos columnas de Checkbox, las cuales indican, en el mismo orden en que está el título de este apartado, los objetivos a cumplir, es decir, el primer Checkbox sería para Tarsier, el segundo para KyMAN y el tercero a angelus.

  • Crear una cuenta GitHub.
    • Publicar el proyecto.
    • Poner el proyecto para ambos como desarrolladores.
  • Crear página de Crowdfounding
    • Añadir las direcciones de Crowdfounding.

Tarsier, KyMAN y/o angelus

Aquí pasa un poco como en el anterior caso, la diferencia es que con tal de que uno de los dos halla cumplido el objetivo llegaría para considerarlo completado.

  • Testear que todo esté correcto.
  • Mirar el funcionamiento de los Crypto Core QT o conseguir direcciones para Crowdfounding.
  • Colocar los logos de Tarsier.

Tarsier

  • Generar los estilos genéricos a partir de los estilos base que cree KyMAN.
  • Generar el logo del proyecto.
    • Vectorizarlo en entorno cuadrado (SVG).
    • Crear versión sólo negro y trasparente para fuente (SVG).
    • Crear versión a color 32x32 (PNG).
    • Crear versión a color 180x180 (PNG).
    • Crear versión a color 192x192 (PNG).
    • Crear versión a color 270x270 (PNG).
    • Crear versión a color 512x512 (PNG).
  • Establecer gama de colores en la configuración del SCSS acordes con el logo.
    • Cambiar colores/tonos del logo o del SCSS hasta que queden acordes e iguales.
    • Se pueden usar estrategias de contrarios y demás.
  • Montar los estilos responsitivos.
  • Montar SEO.

KyMAN

  • Renombrar todo el proyecto a WMarkDown.
  • Proponerle el sistema de Crowdfounding.
    • por direcciones independientes según cada parte y por lo que quiera colaborar el donante.
    • Direcciones únicas y luego suministramos o dividimos.
    • Aprobado.
  • Montar los estilos base.
    • Implementar fuentes.
    • Establecer los ficheros de SASS.
      • Se incluye la configuración SCSS.
    • Iconificar.
    • Dar formato final.
  • Montar los módulos:
    • Cabeceras.
      • Menú sobre cabeceras.
      • Anidar cabeceras según nivel en el menú.
        • No está anidado pero sí usa un sistema de niveles.
      • Ocultar y mostrar menús. Gestionar estilos.
    • Párrafos.
    • Formato de texto. Solo negritas y cursivas.
    • Bloques de código o contenido plano.
      • Identificar bloques de contenido plano.
      • Implementar Syntax Highlighter.
      • Implementar LaTeX, con seudónimo "Maths".
    • Checkbox, Radio Buttons y Ticks.
    • Listas.
      • Gestionar anidamientos en HTML sobre UL y OL.
      • Añadir gráfica de evolución sobre una lista con Checks.
    • Inclusión, implementación o importación de múltiples ficheros modo OnePage.
      • Establecer vínculo Hash y de fichero.
    • Quotes.
    • Implementar parámetros.
    • Links.
      • Links normales.
      • Links MarkDown.
      • Links MediaWiki.
      • Documentar.
    • Multimedia.
      • Los IFRAME no son gestionables desde CSS por CORS. Dependen de su contenedor.
      • Imágenes.
      • Vídeos.
        • Montar vídeos en single y múltiple.
        • Montar gestión del MIME en PHP y JS.
          • Montar gestión dinámica sin carga inicial de los MIME y las extensiones.
      • Vídeos sobre plataformas embedadas.
        • Youtube.
        • Vimeo.
        • Facebook.
          • Da problemas con certificados autofirmados.
        • Twitch.
          • Da problemas con certificados autofirmados.
      • Audios.
      • Audios sobre plataformas embedadas.
        • Soundcloud.
          • No puede agregarse a partir de la URL.
      • Sliders.
      • Gestionar "NOSCRIPT" para SEO en los IFRAME.
      • Cambiar punto de montaje de los Media a un Módulo completo independiente.
    • Crear sistema de diccionarios para las páginas.
      • Montar gestión de palabras sobre TextNodes.
      • Gestionar ignorador de espacios.
      • Gestionar GUI de búsqueda.
        • Corregir Scroll.
      • Aplicar resultados de patrones a los resultados.
      • Gestionar múltiples diccionarios.
        • Inicialmente, pensando en anidaciones.
    • Montar Módulo de escapes.
  • Implementar.
    • Sistema de gestión de diagramas.
      • Elijo Mermaid contra JS, su versión original por ser un resultado HTML.
    • Syntax Highlighter.
      • Elijo "highlighter.js", una librería ligera, abierta y gratuíta para JS en navegador.
    • Implementar intérprete de LaTeX.
  • Montar el fichero JSON para gestión de eliminación de ficheros para actualizarlos.
    • Gestionar idiomas a partir de un elemento del Path.
    • Montar opción de "delete" para Git y así no montar ni JSON y HTML en Git.
      • Sería opcional y para que no halla conflictos Merge en Git.
  • Cambiar de un sistema de diccionario a un sistema vectorial el parámetro de la configuración "default_modules".
    • Se requiere por compatibilidad de orden con otros medios como Python.
  • Montar textos para el HTML base.
  • Establecer sistema para los SEO Metas contra el HTML base.
  • Añadir sistema de comentarios, Likes y visualizaciones.
    • Gestionar el SQLite.
    • Gestionar PHP.
      • Gestionar los procedimientos almacenados (Servicios).
      • Gestionar controladores.
      • Gestionar JS.
    • Gestión de visitas.
    • Gestión de usuarios.
    • Gestión de Likes.
    • Gestión de comentarios.
  • Documentar instalación del GitLab contra un Proxy Nginx externo.
  • Generar un archivo PHP Updater.
    • Ha de Checkar nuevas versiones completas desde Git.
    • Ha de Checkar que si hay versiones nuevas para compilar la documentación.
    • *Sistema diseñado a partir de la idea de inoro.*
  • Añadir los ficheros de los componentes externos al CDN.
  • Externalizar en todos los proyectos que deriven de éste todos los parámetros de configuración a Secrets como Common.
    • Esto permitirá compatibilizar proyectos locales con los de los servidores.
    • La idea es que solo halla que hacer "git pull" en los servidores.
  • Montar sistema de descarga en documento de la información en los siguientes formatos.
    • Texto plano.
    • WMarkDown.
    • HTML.
    • XML.
    • MySQL (MariaDB).
    • SQL Server.
    • SQLite.
    • DOC
    • ODT
    • PDF
  • Documentar:
    • Secrets.
    • Implementación.
    • Creación de un complemento.
  • Montar Padding al contenido siguiendo la idea de inoro.
  • Aplicar I18N contra entorno de variables PHP.
  • Montar detector y cambiador de Versión Móvil.
  • Montar responsitividad por rangos en el lado más estrecho.
  • Montar modificador de tamaño de letra.
  • Montar el ScriptsAnalyzer.
    • Montar el analizador de Scripts:
      • PHP.
      • JS/ECMA.
      • Python.
      • SQL (MariaDB, SQLite y SQL Server).
      • C#.
    • Montar Paths excluídos.
    • Montar Paths incluídos.
  • Añadir Script automático para dar Status al logo (loading, error, ok).
  • Quitar el HTML resultante de la compilación del WMD y precompilar en el servidor.
    • El objetivo es que se vea claramente, en el Git, el porcentaje de código real.
  • Arreglar el Bug 20221012.
  • Agregar el Pusher.

angelus

- Completar documentación haciendo de mano inocente.

Files