Markdown-støtte i Vortex

Vortex har enkel støtte for opplasting og redigering av Markdown dokumenter. Det finnes mange Markdown varianter, og Markdown støtten i Vortex er fortsatt i en tidlig fase. Dette innebærer at det fortsatt kan komme endringer i måten Markdown fungerer på i Vortex, men vi håper å unngå endringer som ikke er bakoverkompatible.

Markdown støtten i Vortex er basert på pegdown (laget i Java, som Vortex).

Markdown-dialekter i Vortex

Markdown støtten i Vortex tar utgangspunkt i John Grubers opprinnelige Markdown. Vi har valgt å skru på mange av mulighetene for utvidelser i pegdown, men ikke alle.

GitHub har vært viktig for å øke bruken av Markdown, og vi har tatt med mange av utvidelsene som er inspirert av GiHub.

Markdown krever i utgangspunktet doble linjeskift (eller to mellomrom før siste linjeskift) for å bryte linjer i tekst. Noen dialekter bryter linjer ved et enkelt linjeskift isteden (basert på GitHub-flavoured-Markdown, selv om GitHub relativt nylig har gått bort fra det i hvert fall i mange sammenhenger).

Vi har valgt å støtte begge typer håndtering av linjeskift, basert på ulik innholdstype (som igjen normalt settes basert på filendelse).

Innholdstype: Markdown

Filtype i Vortex (kan ses på Om-flappen): text/markdown
Settes ved opplasting med filendelser: .md .mkdn

Utvidelser som er skrudd på i pegdown:

Innholdstype: Markdown GFM (med harde linjeskift)

Filtype i Vortex (kan ses på Om-flappen): text/markdown.GFM
Settes ved opplasting med filendelser: .markdown .mdown

Utvidelser som er skrudd på i pegdown (i tillegg til de for innholdstype Markdown beskrevet over):

Tittel i Markdown-dokumenter

Tittel hentes fra første overskrift (H1-H3 element) i dokumentet når det er transformert til HTML.

I Markdown tilsvarer dette normalt første overskrift i dokumentet av:

# h1 overskrift 
## h2 overskrift
## h3 overskrift

Innledning i Markdown-dokumenter

Innledning hentes fra første <p> element i dokumentet når det er transformert til HTML. Dette vil normalt være første avnitt med tekst (som ikke er en overskrift). Avsnittet brukes i lister o.l. slik som innledning brukes fra artikler, men det formateres ikke spesielt ved visning av Markdown.

Det er for tiden vanskelig å unngå å få innledning, og det er vanskelig å få en innledning med flere avsnitt.

Tips

Slik oppretter du et Markdown-side

Den enkleste måten å opprette en Markdown-side er å først skrive dokumentet i en teksteditor på egen maskin, for deretter å laste det opp i administrasjonsgrensesnittet i Vortex. For eksempel mitt-dokument.md, med følgende innhold:

# Mitt dokument
Dette er et Markdown-dokument som heter «mitt-dokument.md».

Fordi filendelsen i dette dokumentet er «.md» vil det bli gjenkjent 
som Markdown når det lastes opp i Vortex.

Dokumentet kan redigeres videre i Vortex («Rediger kildekode»), 
eller over WebDAV.

Caching

Markdown transformeres til HTML ved visning, og resulatet caches normalt i noen minutter (slik at det ikke transformeres på nytt selv om kildekoden endres).

Dette kan være en ulempe mens man redigerer et dokument, siden man ikke nødvendigvis får se resultatet av endringen med en gang.

Man kan omgå dette problemet ved å arbeide inne i Vortex-administrasjonsmodus og se på dokumentet på Vis-flappen. Der vil siden oppdateres i hvert fall hver gang man bytter flapp.

Markdown som indeks-fil i en mappe

index.md, index.mkdn, index.markdown og index.mdown fungerer som index-fil i en Vortex mappe. Det er også mulig å laste opp et markdown-dokument (med en filendelse som gjør at dokumentet tolkes som Markdown), og så endre navnet etterpå til index.html. Dette dokumentet er laget på den måten.

<div> elementer

Hvis man har behov for en HTML <div> elementer i Markdown, men likevel vil fortsette å skrive i Markdown, anbefales følgende løsning:

<DIV markdown="1" class="eksempelklasse">

Fortsett å skrive *Markdown* etter en tom linje.
Trikset er å skrive åpnings DIV'en med store bokstaver. Da gjenkjennes den ikke av pegdown.
`markdown='1'` har ikke noen virkning i pegdown, men brukes for å oppnå det samme i noen andre Markdown 
dialekter, og gjør det tydelig hva man vil oppnå. Tom linje etter `<DIV>` vil gjøre at det virker også i 
f.eks. CommonMark. 

</DIV>

Blir transformert:

Fortsett å skrive Markdown etter en tom linje. Trikset er å skrive åpnings DIV'en med store bokstaver. Da gjenkjennes den ikke av pegdown. markdown='1' har ikke noen virkning i pegdown, men brukes for å oppnå det samme i noen andre Markdown dialekter, og gjør det tydelig hva man vil oppnå. Tom linje etter <DIV> vil gjøre at det virker også i f.eks. CommonMark.

Kodeblokker

Det hender at det blir problemer med "fenced code blocks", spesielt innenfor lister. I slike tilfeller kan det være lettere å få det til å virke med standard Markdown kodeblokker.

Dette er et område hvor Markdown ikke er godt nok standardisert.