Recetas¶
Markdown¶
Ejemplos de cómo generar documentación con Markdown.¶
Incluyo distintos ejemplos de cómo generar documentación a partir de Markdown. Aunque son ejemplos concretos pueden servir para cas cualquier caso.
Los tipos de documentación que genero son:
- Para imprimir y leer en ordenador:
- pdf de tamaño a4
- Para leer en el ereader:
- epub
- en caso de que no se pueda generar epub (porque contenga código LaTeX, por ejemplo) se genera un pdf de tamaño a6
- En el caso de música tengo que instalar el paquete lilyglyphs:
1. Se copia el directorio en
tex/latex
del MKITEX (la instalación puede estar en Archivos de Programa o en AppData\Roaming 2. Se copia el subdirectoriofonts
enfonts/opentype
cambiando el nombre a `‘emmentaler’ 3. Se actualiza la base de datos (MikTeX Console -> Tools)
- En el caso de música tengo que instalar el paquete lilyglyphs:
1. Se copia el directorio en
- Para incluir como nota en Synology Note Station
- genero un html standalone (para que se copien bien las imágenes) y lo hago con copy-paste
- en el caso de que no se pueda generar html (porque contenga código LaTeX, por ejemplo) se genera un pdf y se divide en imágenes
Los ficheros incluidos son los necesarios para hacer la compilación. Utilizo dos casos:
- cuestiones Jcyl: con el que genero pdf a4, epub y html
- musica: con el que genero pdf a4 y pdf a6 (con el LaTeX incluido no consigo hacer ni epub ni html)
- Tengo que seguir probando, pero de momento me apaño. Ver pruebas.txt
Los documentos los hago con Markdown (utilizo para la edición vscode), las imágenes principalmente en png (con el svn no se genera correctamente el epub) y la generación se hace con pandoc y LaTeX.
Añadir código LaTeX dentro de Markdown¶
Para poder usar código LaTeX en Markdown sin tener que meterlo dentro de se puede añadir directamente y luego hacer la compilación con pandoc añadiendo la opción:
pandoc -f markdown+raw_tex ....
Añade una imagen, de forma que no sea flotante si se convierte a pdf mediante pandoc y latex¶

\
Nota: es importante añadir un espacio después de
\ -->
Comandos para generar la documentación¶
pdf a4¶
pandoc -N a4.yaml cuestiones.md --highlight-style pygments --pdf-engine=xelatex -o cuestiones.pdf
html (para copiarlo al Synology Note Station)¶
pandoc -s --mathjax -c cuestiones.css --self-contained --highlight-style pygments --metadata-file=html.yaml cuestiones.md -o cuestiones.html
epub¶
pandoc -s --mathjax --highlight-style pygments --metadata-file=epub.yaml cuestiones.md -o cuestiones.epub
pdf a6¶
pandoc -N --pdf-engine=xelatex musica.md -f markdown+raw_tex -o musicaReader.pdf
Corregir líneas de código que no caben en la página (Markdown)¶
Añadir lo siguiente a las cabeceras latex:
\lstset{breaklines=true}
\lstset{language=[Motorola68k]Assembler}
\lstset{basicstyle=\small\ttfamily}
\lstset{extendedchars=true}
\lstset{tabsize=2}
\lstset{columns=fixed}
\lstset{showstringspaces=false}
\lstset{frame=trbl}
\lstset{frameround=tttt}
\lstset{framesep=4pt}
\lstset{numbers=left}
\lstset{numberstyle=\tiny\ttfamily}
\lstset{postbreak=\raisebox{0ex}[0ex][0ex]{\ensuremath{\color{red}\hookrightarrow\space}}}
y compilar con pandoc añadiendo --listings --latex-engine=xelatex
Escapar caracteres en Markdown¶
Los siguientes caracteres se pueden escapar añadiendo delante \
\ backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash mark
+ plus sign
- minus sign (hyphen)
. dot
! exclamation mark
Para escapar la barra vertical en una tabla se puede usar el código ascii en html:
|
Cabecera yaml para ereader 6 pulgadas¶
---
title: Lenguaje musical
author: Roberto Hernando
fontsize: 14pt
header-includes:
#- \AtBeginDocument{\let\maketitle\relax}
- \usepackage{atbegshi}
- \AtBeginDocument{\AtBeginShipoutNext{\AtBeginShipoutDiscard}} #Borra la página de título (uso portada propia)
- \usepackage[papersize={3.6in,4.8in},hmargin=0.1in,vmargin={0.1in,0.1in}]{geometry}
- \usepackage[utf8]{inputenc}
- \usepackage{fontspec}
- \usepackage{lilyglyphs}
- \setmainfont{Cambria}
- \usepackage{microtype}
- \usepackage[spanish]{babel} #español
- \usepackage[font=small,labelformat=simple,]{caption}
- \usepackage{fancyhdr}
- \pagestyle{fancy}
- \fancyhead{}
- \fancyfoot{}
- \setlength{\abovecaptionskip}{2pt}
- \setlength{\belowcaptionskip}{0pt}
- \setlength{\textfloatsep}{2pt}
- \setlength{\floatsep}{2pt}
- \setlength{\intextsep}{2pt}
---
Pandoc¶
Usar la plantilla eisvogel para LaTeX con pandoc¶
Copiar el fichero eisvogel.latex en C:\Users\USERNAME\AppData\Roaming\pandoc\templates
.
LaTeX¶
Para que LaTeX divida líneas largas de textt (código)¶
El problema es que por defecto el tipo de letra textt (el que se usa para código) no tiene hyphenation definido.
Se hace incluyendo el paquete:
\usepackage[htt]{hyphenat}
No parece que funcione :-(
Corregir error LaTeX Error: Too deeply nested al exportar un markdown a pdf¶
\usepackage{enumitem}
\setlistdepth{9}
\setlist[itemize,1]{label=$\bullet$}
\setlist[itemize,2]{label=$\bullet$}
\setlist[itemize,3]{label=$\bullet$}
\setlist[itemize,4]{label=$\bullet$}
\setlist[itemize,5]{label=$\bullet$}
\setlist[itemize,6]{label=$\bullet$}
\setlist[itemize,7]{label=$\bullet$}
\setlist[itemize,8]{label=$\bullet$}
\setlist[itemize,9]{label=$\bullet$}
\renewlist{itemize}{itemize}{9}
\setlist[enumerate,1]{label=$\arabic*.$}
\setlist[enumerate,2]{label=$\alph*.$}
\setlist[enumerate,3]{label=$\roman*.$}
\setlist[enumerate,4]{label=$\arabic*.$}
\setlist[enumerate,5]{label=$\alpha*$}
\setlist[enumerate,6]{label=$\roman*.$}
\setlist[enumerate,7]{label=$\arabic*.$}
\setlist[enumerate,8]{label=$\alph*.$}
\setlist[enumerate,9]{label=$\roman*.$}
\renewlist{enumerate}{enumerate}{9}
Cómo añadir entrada en bibliografía sin cita¶
\nocite{libro}
Corregir error SSL al al actualizar o instalar paquetes¶
Añadir la variable de entorno MIKTEX_MPM_REMOTESERVICE6210=multiplexor
(de StackExchange)
Hugo¶
Como añadir un enlace en Hugo para que me funcione correctamente en servidor y en local¶
El truco es añadir los enlaces (por ejemplo a imágenes) con la ruta absoluta en vez de relativa.
Por ejemplo:

\
Imágenes en Hugo con caption¶
single.html y list.html
{{ partial "header.html" . }}
<!-- Convierte las imágenes con alt (las que se etiquetan en markdown
en figuras añadiendo como pie de imagen el alt -->
{{ $reIn1 := "<p><img src=\"(.*)\" alt=\"(.*)\"></p>" }}
{{ $reOut1 := "<figure><img src=\"$1\" alt=\"$2\"> <figcaption>$2</figcaption></figure>" }}
{{ $finalContent := .Content | replaceRE $reIn1 $reOut1 |safeHTML }}
{{ $finalContent }}
<!-- {{ .Content }} -->
Lilypond¶
Dibujar acordes de piano¶
%% http://lsr.di.unimi.it/LSR/Item?id=791
%% see also http://lilypond.org/doc/v2.18/Documentation/snippets/keyboards
#(define KEY-POS-LIST '(
(c . 1) (cis . 1.5) (des . 1.5) (d . 2) (dis . 2.5) (ees . 2.5) (e . 3)
(f . 4) (fis . 4.5) (ges . 4.5) (g . 5) (gis . 5.5) (aes . 5.5) (a . 6)
(ais . 6.5) (bes . 6.5) (b . 7) (c' . 8) (cis' . 8.5) (des' . 8.5) (d' . 9)
(dis' . 9.5) (ees' . 9.5) (e' . 10) (f' . 11) (fis' . 11.5) (ges' . 11.5) (g' . 12)
(gis' . 12.5) (aes' . 12.5) (a' . 13) (ais' . 13.5) (bes' . 13.5) (b' . 14) (c'' . 15)))
#(define (black-key? num )
(member num '(cis des dis ees fis ges gis aes ais bes
cis' des' dis' ees' fis' ges' gis' aes' ais' bes')) )
#(define (key-to-pos key ypos)
(let ((keypos (assq key KEY-POS-LIST)))
(if (not keypos)
(ly:error (_ "keyboard diagram error - unkown note '~a'") key)
(cons (- (cdr (assq key KEY-POS-LIST)) 0.5) ypos))))
#(define (make-keys l1 width off height fill)
(if (null? l1)
empty-stencil
(ly:stencil-add
(ly:stencil-translate
(make-line-stencil 0.1 0 0 0 height)
(if fill
(cons (- (car l1) (/ width 2)) off) ;
(cons (- (car l1) 1) off)))
(make-keys (cdr l1) width off height fill))))
#(define (make-keys-black l1 width off height fill)
(if (null? l1)
empty-stencil
(ly:stencil-add
(ly:stencil-translate
(ly:round-filled-box `(0 . ,width) `(0 . ,height) 0)
(if fill
(cons (- (car l1) (/ width 2)) off) ;
(cons (- (car l1) 1) off)))
(make-keys-black (cdr l1) width off height fill))))
#(define (make-dot key)
(if (black-key? key)
(ly:stencil-in-color
(ly:stencil-translate (make-circle-stencil 0.27 0 #t) (key-to-pos key 2.5)) 1 1 1)
(ly:stencil-translate (make-circle-stencil 0.32 0 #t) (key-to-pos key 0.8)) ))
#(define (make-dot-list l1)
(if (null? l1)
empty-stencil
(ly:stencil-add
(make-dot (car l1))
(make-dot-list (cdr l1)))))
#(define-markup-command (keys layout props arg1) (list?)
(ly:stencil-add
(make-line-stencil 0.1 0 0 14 0)
(make-line-stencil 0.1 0 6 14 6)
(make-keys '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15) 1 0 6 #f)
(make-keys-black '(1 2 4 5 6 8 9 11 12 13 ) 0.65 2 4 #t)
(make-dot-list arg1 )))
cnine=\markup\keys #'(c e g bes d' )
cmnine=\markup\keys #'(c ees g bes d')
cmninealt=\markup\keys #'(c bes d' ees' g')
\relative c' {
<c e g bes d>4^\cnine^"C9" r r2 r1
<c ees g bes d>4^\cmnine^"Cm9" r r2 r1
<c bes' d ees g>4^\cmninealt^"Cm9" r r2
}
Dibuja un teclado en lilypond¶
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% LSR workaround:
#(set! paper-alist (cons '("snippet" . (cons (* 190 mm) (* 155 mm))) paper-alist))
\paper {
#(set-paper-size "snippet")
tagline = ##f
indent = 0
}
\markup\vspace #1
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\language "deutsch"
%% often people think that the black keys are centered to the white keys
%% even in piano teaching books keyboards are drawn this way
%% this is not the case, black keys are positioned surprisingly excentric
%% http://lsr.di.unimi.it/LSR/Item?id=791 inspired me
%% to draw a keyboard with following features:
%% - scalable
%% - correct positioning of the black keys
%% - entering of notes which are represented by dots
%% created by Manuela
%% feel free to modify and distribute
%% all values are measured by myself on my piano
#(define white-key-width 23.5) %% the width of a white piano key
#(define white-key-height 150) %% the height of a white piano key
#(define black-key-width 15) %% the width of a black piano key
#(define black-key-height 95) %% the height of a black piano key
#(define black-key-y-start (- white-key-height black-key-height)) %% the y-coordinate of black keys
%% left coordinate of black keys cis/des fis/ges
%% n=0 oder n=3 (index number of global default scale)
#(define black-key-cis-start 13)
%% left coordinate of centered black keys gis/as
%% n=4 (index number of global default scale)
#(define black-key-gis-start 16)
%% left coordinate of right black keys dis/es ais/b
%% n=1 oder n=5 (index number of global default scale)
#(define black-key-dis-start 19)
#(define octav-distance (* 7 white-key-width))
%% define circle diameter for the dots
%% just try what looks fine
#(define kreis-dm (* black-key-width 0.5)) %% circle diameter
%% routine to move and scale a markup
#(define-markup-command (move-and-scale layout props mymark faktor x-offset)
(markup? number? number?)
(ly:stencil-translate-axis
(ly:stencil-scale
(interpret-markup layout props mymark)
faktor faktor)
x-offset X))
%% single white key
wh-taste =
#(make-connected-path-stencil
;; creates a square which is transformed
;; according to width and height of a white key
'((0 0) (1 0) (1 1) (0 1))
0.1 ;; thickness
white-key-width
white-key-height
#t ;; close path
#f ;; do not fill path
)
w-tasten=
#(apply
ly:stencil-add
wh-taste
(map
(lambda (i) (ly:stencil-translate-axis wh-taste (* i white-key-width) X))
(iota 6 1 1)))
%% combining two octaves
dos-w-octavas=
#(ly:stencil-add
w-tasten
(ly:stencil-translate-axis w-tasten octav-distance X))
%% defining single black key
bl-taste=
#(make-connected-path-stencil
'((0 0) (1 0) (1 1) (0 1) )
0.1
black-key-width
black-key-height
#t ;; close path
#t ;; fill path
)
%% combining 5 black keys for one octave
b-tasten =
#(ly:stencil-add
(ly:stencil-translate
bl-taste
(cons black-key-cis-start black-key-y-start))
(ly:stencil-translate
bl-taste
(cons (+ black-key-dis-start white-key-width ) black-key-y-start))
(ly:stencil-translate
bl-taste
(cons (+ black-key-cis-start (* white-key-width 3) ) black-key-y-start))
(ly:stencil-translate
bl-taste
(cons (+ black-key-gis-start (* white-key-width 4) ) black-key-y-start))
(ly:stencil-translate
bl-taste
(cons (+ black-key-dis-start (* white-key-width 5) ) black-key-y-start)))
%% combining to octaves black keys
dos-b-octavas=
#(ly:stencil-add
b-tasten
(ly:stencil-translate-axis b-tasten octav-distance X))
complete-keyboard-two-octaves=
#(ly:stencil-add
dos-w-octavas
dos-b-octavas)
#(define (music-name x)
(if (not (ly:music? x))
#f
(ly:music-property x 'name)))
#(define (naturalize-pitch p)
(let ((o (ly:pitch-octave p))
(a (* 4 (ly:pitch-alteration p)))
;; alteration, a, in quarter tone steps,
;; for historical reasons
(n (ly:pitch-notename p)))
(cond
((and (> a 1) (or (eq? n 6) (eq? n 2)))
(set! a (- a 2))
(set! n (+ n 1)))
((and (< a -1) (or (eq? n 0) (eq? n 3)))
(set! a (+ a 2))
(set! n (- n 1))))
(cond
((> a 2) (set! a (- a 4)) (set! n (+ n 1)))
((< a -2) (set! a (+ a 4)) (set! n (- n 1))))
(if (< n 0) (begin (set! o (- o 1)) (set! n (+ n 7))))
(if (> n 6) (begin (set! o (+ o 1)) (set! n (- n 7))))
(ly:make-pitch o n (/ a 4))))
#(define (white-key? p)
(let
((a (ly:pitch-alteration (naturalize-pitch p))))
(if (= a 0)
#t
#f)))
#(define (start-point-key p)
;; calculation the starting point of a key
;; depending on the pitch p
;; result (x . y)
(let*
((m (naturalize-pitch p))
(o (ly:pitch-octave m))
(a (ly:pitch-alteration m))
;; we must naturalize pitch otherwise wrong result for eis e.g.
;; we subtract the alteration from the notename and add a half
;; so we end up at the same note despite flat oder sharp
;; cis is drawn the same as des e.g.
(n (ly:pitch-notename m))
(n1 (+ n a -0.5))
(x-shift (* o 7 white-key-width))
)
(cond
((eq? a 0)
;; alteration eq 0
;; no alteration ==> white key
(cons (+ (* n white-key-width) x-shift) 0 ))
((or (= n1 0) (= n1 3))
;; "left" black keys cis/des and fis/ges
;; notename=0 or 3 and alteration
;; n=0 oder n=3
(cons (+ (* n1 white-key-width) black-key-cis-start x-shift ) black-key-y-start ))
((or (= n1 1) (= n1 5))
;; "right" black keys dis/es and ais/b
;; notename=0 or 3 and alteration
;, n=1 oder n=5
(cons (+ (* n1 white-key-width) black-key-dis-start x-shift ) black-key-y-start ))
(else
;; only one left, the centered black key gis/as
(cons (+ (* n1 white-key-width) black-key-gis-start x-shift) black-key-y-start )))))
#(define (make-dot p)
(let* ((start-p (start-point-key p)))
(if (white-key? p)
(ly:stencil-in-color
(ly:stencil-translate
(make-circle-stencil kreis-dm 0 #t)
(cons
(+ (car start-p) (/ white-key-width 2 ))
(+ (cdr start-p) (/ (- white-key-height black-key-height) 1.5))))
0.2 0.5 0.5) ;; color petrol
(ly:stencil-in-color
(ly:stencil-translate
(make-circle-stencil kreis-dm 0 #t)
(cons
(+ (car start-p) (/ black-key-width 2 ))
(+ (cdr start-p) (/ black-key-height 5))))
0.4 0.7 0.7) ;; color slightly lighter petrol than above
)))
%% creating a single stencil of multiple dots for a list of pitches
#(define (make-dot-list l1)
(if (every ly:pitch? l1)
(apply ly:stencil-add (map make-dot l1))
empty-stencil))
#(define-markup-command (complete layout props the-chord)
(ly:music?)
(ly:stencil-scale
(ly:stencil-add
dos-w-octavas
dos-b-octavas
(make-dot-list
(map
(lambda (m) (ly:music-property m 'pitch))
(extract-named-music the-chord 'NoteEvent))))
0.035 0.035))
ChordwithKeyboard=
#(define-music-function (parser location the-chord)
(ly:music?)
#{ <>^\markup \complete #the-chord $the-chord #})
twoOctaves=
\markup {
\combine \stencil \dos-w-octavas
\combine \stencil \dos-b-octavas
\null
}
\markup "Draw a correct Keyboard with 2 octaves"
\markup \move-and-scale \twoOctaves #0.3 #0
\markup { \null \vspace #4 "Draw a correct Keyboard with 2 octaves (approx. one staff high) and a chord" }
\score {
<<
\new Staff \ChordwithKeyboard \chordmode { b:sus4 }
\new ChordNames \chordmode { b:sus4 }
>>
}