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.