Computing & ElectronicsDossier

markdown on line

Remarkable demo web

Per formattare “al volo” il testo, esiste il markdown, un linguaggio che unisce il testo alla formattazione.
Lo si scrive velocemente, utilizzando quasi sempre solo la tastiera (senza dover andare al menu con il mouse).
E lo si rilegge anche molto bene, perché la formattazione non è invadente.
Vediamo 2 possibilità con software opensource:

 

L’istallazione, in entrambi i casi, è semplicissima:  si scarica dal web (con wget) e si installa on gdebi.  Attualmente la versione di remarkable è 1.87 (vedi https://remarkableapp.github.io/linux/download.html ) quindi:
wget https://remarkableapp.github.io/files/remarkable_1.87_all.deb
sudo gdebi remarkable_1.87_all.deb

Al volerlo installare, ubuntu lo descrive e chiede “vuoi installare i pacchetti sorgente”?

A free fully featured markdown editor.
Remarkable is a free fully featured markdown editor. It has a syntax
like Github flavoured markdown. With it you can write markdown and view
the changes as you make them in the live preview window. You can export
your files to a variety of formats. There are multiple styles available
along with extensive configuration options so you can set it up exactly
how you like.
Do you want to install the software package? [y/N]:

Stessa cosa con haroopad:

wget https://bitbucket.org/rhiokim/haroopad-download/downloads/haroopad-v0.13.1-x64.tar.gz

In caso di errori, per remarkable, eseguire:
user@A:~$ sudo pip install --upgrade beautifulsoup4
user@A:~$ sudo pip install --upgrade html5lib

 

La formattazione del testo

Vediamo come utilizzarlo in casi speciali (per l’utilizzo “ordinario”, grassetto, italico, rimandiamo a questa guida https://help.github.com/articles/basic-writing-and-formatting-syntax/#lists).

Ad esempio, per inserire una nota che non sia visibile nel testo finale, si utilizza la sintassi del commento in html, quindi:

<!– testo non visibile –>

 

Liste ordinate

Per non interromprere la continuitiá uno spazio ed indentate.

Resize image

Se vogliamo inserire un’immagine con una dimensione differente, in remarkable, non un funziona il fatto di aggiungere la dimensione dopo, come in altri formattatori, ma dobbiamo ricorrere all’html.

  • no
    • ![impulzia](/home/ca/git/manuales/impu.png height = 10px)
  • si
    • <img src=”/home/ca/git/manuales/impu.png” width=”80″ height=”60″>

 

 

Si può provare “al volo” il markdown alla pagina https://jonschlinkert.github.io/remarkable/demo/

Remarkable demo web

 

 

Markdown On line

Come sfruttare in una pagina web tutte questi testi facilmente formattati con il markdown? Consigliamo di usare il pacchetto python chiamato mkdocs, che crea varie pagine web “coerenti” per mostrare i nostri testi.

L’istallazione è estremamente semplice (la vedremo alla fine) ed il lancio altrettanto: nella directory in cui abbimo il file delle impostazioni (mkdocs.yml) digitiamo mkdocs serve per far partire il server che mostrerá alla porta 8000 i testi.

Lasciamo per dopo l’installazione, vediamo prima come strutturare pagine coerenti, ad esempio, rilazionando, con dei collegamenti o link, fra di loro.

Collegamenti fra le diverse pagine dei testi markdown

Si creano con questa sintassi:

[testo che appare](nome_del_file)

Esempio

[007 login.md](007_Aceder.md)

[007 login](007_Aceder)

Notare come si possa mettere o omettere l’estensione .md. Non va messo docs, va bene un percorso relativo (cioè non funzionerebbe un link scritto così [007 docs/login.md](docs/007_Aceder.md) )

 

La struttura del menu

Si possono innestare le pagina, cosi da creare menu piu sintetici e leggibili, mettendo poi, nelle singole voci, maggiori informazioni.

file system example

Corrisponde a questi file e directory:

  • Home.md
  • Examples.md
  • img/favicon.png
  • Sub dir
  • Sub dir/Sub page.md
  • Sub dir/Sub dir 2
  • Sub dir/Sub dir 2/Sub page 2.md

Per il solo fatto di strutturare un file markdown dentro una directory mkdocs la interpreta come un sub-voce del menu. Notate che la directory img non contiene md file e quindi non viene mostrata nel menu.

 

Testo delle voci del menu

Il testo che appare nel menu varia a seconda della posizione:

se si è nella pagina stessa, appare il testo del titolo principale, altrimenti il nome del file stesso.

 

Immagini

In mkdocs non funziona la definizione di un’immagine con tags html, dei tre modi, funziona solo il primo:

![](../impu.png)
<img src="../imp.png" width="80" height="60">
<img src="../impu.png" >

html tag img doesn't work in mkdocs

Installazione e lancio

Supponendo nella vostra macchina già sia installato python, vanno bene le versioni 2.7, 3.3, 3.4, 3.5 e pypy, mkdocs si installa con pip, tipocamente con permessi di sudo:

sudo pip install mkdocs

 

Lo si lancia, come detto, con serve:
user@PC_A:~/git/manuales/mia_directory_con_file_yml$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
WARNING - The page "subitem21.md" contained a hyperlink to "007_Aceder.md" which is not listed in the "pages" configuration.
[I 171124 07:11:36 server:283] Serving on http://127.0.0.1:8000
[I 171124 07:11:36 handlers:60] Start watching changes
[I 171124 07:11:36 handlers:62] Start detecting changes

Se il file yml non fosse presente, ce lo ricorda e si blocca (non sapendo mkdocs che fare).


user@PC_A:~$ mkdocs serve
INFO - Building documentation...

Config file ‘/home/user/mkdocs.yml’ does not exist.
user@PC_A:~$

 

Un interessante opzione la dà la specifica –dev-addr, permette di lanciare il manuale mkdocs in un’altra porta rispetto alla 8000, presa di default, cosí da avere, ad esempio in locale, più di un manuale aperto.


user@PC:~/$ mkdocs serve --dev-addr=localhost:8002

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *