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.
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>
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.
|
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>
|
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.
|
|
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.
|
|
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:
Con llaves:
Uso del caracter V:
|
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.
Links directos
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 |
Links locales
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 |
Links referenciados
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/
|
|
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.
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]]
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.
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.
|
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.
links_group
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:
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.
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.
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]]
|
|
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.
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...]]
|
|
|
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]]
|
|
|
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]]
|
|
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
]]
|
|
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
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.
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>
|
| Cabecera | ejemplo1 | ejemplo2 | ejemplo3 | ejemplo4 | ejemplo4 |
|---|
| 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. |
|---|
|
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.
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"]
|
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/
WMarkDown