Guide til dokumentasjon

Her finner du de vanligste tingene du trenger når du redigerer en .md-fil. Kopier et eksempel og bytt ut teksten med din egen.

Ny side

Start filen med tittel, sidebar og URL:

---
title: Navnet som vises øverst
sidebar: main_sidebar
permalink: mitt_unike_sidenavn.html
---

Legg deretter siden inn i _data/sidebars/main_sidebar.yml:

- title: Navnet i sidebaren
  url: /mitt_unike_sidenavn.html
  output: web

Bruk en unik permalink uten mellomrom. Hvis en YAML-verdi inneholder kolon eller #, setter du verdien i anførselstegn:

title: "API: oppsett og bruk"
summary: "Steg 1: opprett en klient"

Redigere en eksisterende side

Rediger kildefilen, som vanligvis ligger under pages/. Filene i _site/ er generert av Jekyll og blir overskrevet ved neste bygg.

Hvis du endrer permalink, må du også endre url i den aktuelle sidebar-filen og kontrollere alle lenker som peker til den gamle adressen.

Nyttige valg i frontmatter

Du kan legge til flere felt når siden trenger det:

summary: Kort forklaring av hva siden handler om
keywords: kundeforhold, API, onboarding
image: /images/og-default.png

• summary vises øverst på siden og brukes som beskrivelse i Google og ved deling.
• keywords legges i sidens metadata, men brukes ikke av dagens interne søk. Der er tydelige overskrifter og godt brødinnhold viktigst.
• image velger bildet som brukes når siden deles, for eksempel i Teams eller LinkedIn.

For interne sider og spesialvisninger finnes disse valgene:

noindex: true
hide_title: true
hide_sidebar: true

• noindex: true ber søkemotorer om ikke å indeksere siden. Betasider får dette automatisk.
• hide_title: true skjuler sidetittelen i innholdet.
• hide_sidebar: true gir full bredde og skjuler begge navigasjonskolonnene.

Det aktive interne søket henter innhold fra sider i main_sidebar.yml. Det finnes ikke et aktivt frontmatter-felt for å skjule bare én side fra dette søket. Det eldre feltet search: exclude brukes ikke av dagens søk.

Overskrifter og innholdsfortegnelse

title blir sidens hovedoverskrift. Start innholdet med ##. Overskrifter fra ## til ###### vises automatisk i innholdsfortegnelsen.

## Hovedseksjon
### Underseksjon
#### Detaljnivå

Du kan lenke rett til en overskrift. ID-en lages automatisk av overskriftsteksten:

[Gå til tabeller](#tabeller)

Tekst, lenker og lister

Dette er fet tekst, dette er kursiv, og dette er gjennomstreket. Bruk inline-kode for feltnavn, scopes, filnavn og korte tekniske verdier.

**Fet**, *kursiv*, ~~gjennomstreket~~ og `inline-kode`.

Intern lenke til nivå 4

Ekstern lenke til Bits

[Intern lenke til en side](mitt_sidenavn.html)

[Ekstern lenke](https://example.com/){:target="_blank" rel="noopener"}

Filer i assets/ og e-postadresser lenkes på samme måte:

[Åpne forvaltningsrutinene](assets/Forvaltningsrutiner_saldostudielan.pdf){:target="_blank"}

[Last ned testcasene](assets/Integrasjonstest_Ajourhold_av_OTP_testdata_og_testcaser_V.1.xlsx)

[Send e-post](mailto:dsop@bits.no)

• Første punkt
• Andre punkt
  • Underpunkt

- Første punkt
- Andre punkt
  - Underpunkt

1. Opprett filen.
2. Legg inn frontmatter.
3. Registrer siden i sidebaren.

1. Opprett filen.
2. Legg inn frontmatter.
3. Registrer siden i sidebaren.

Sjekklister er praktiske i utkast og arbeidsbeskrivelser:

• Tittel og permalink er satt
• Lenker er kontrollert

- [x] Ferdig
- [ ] Gjenstår

Informasjonsbokser

Bruk boksene til korte beskjeder:

{% include note.html content="Nyttig tilleggsinformasjon." %}
{% include tip.html content="Anbefalt fremgangsmåte." %}
{% include important.html content="Informasjon leseren må få med seg." %}
{% include warning.html content="En handling som kan gi feil." %}

Trenger du en annen farge, kan du bruke en generell callout. Typene er primary, info, success, warning og danger.

{% include callout.html type="primary" content="Teksten i boksen." %}

Kode

Bruk tre backticks og språk for lengre kode:

{
  "accountReference": "12345678901",
  "status": "ACTIVE"
}

`inline-kode`

```json
{
  "status": "ACTIVE"
}
```

Du kan blant annet bruke json, yaml, bash, javascript, html, xml og text som språk etter backticks.

Tabeller

| Felt | Påkrevd | Beskrivelse |
|:---|:---:|---:|
| `accountReference` | Ja | Kontoens referanse |
| `status` | Ja | Gjeldende status |

Hold tabeller forholdsvis smale, slik at de også fungerer på mobil.

Kolonene styrer justeringen: :--- er venstre, :---: er sentrert og ---: er høyre.

Hvis en celle skal inneholde tegnet |, må det escapes med en omvendt skråstrek:

| Verdi | Betydning |
|---|---|
| `ja \| nei` | Ett av to valg |

Sitater og skillelinjer

Bruk sitat når en tekst skal skilles tydelig fra resten av innholdet.

> Dette er et sitat.

Tre bindestreker lager en skillelinje:

---

Helt øverst i filen brukes --- til frontmatter. Lenger ned blir det en skillelinje.

Bilder

![Beskrivende alternativ tekst](images/filnavn.png)

{% include image.html file="company_logo_big.png" alt="Bits-logo"
   max-width="220" caption="Bildetekst under bildet." %}

Legg bildefilen i images/, og skriv alltid en meningsfull alt-tekst.

Enkel HTML i Markdown

Du kan skrive HTML direkte i en .md-fil. Det er nyttig når vanlig Markdown ikke gir nok kontroll.

<div style="background-color: #e6ffec; border: 1px solid #8bcf9b;
            border-radius: 4px; padding: 12px 16px; margin: 12px 0;">
  <strong>Grønn boks</strong><br>
  Denne boksen er laget med en vanlig <code>div</code> og inline style.
</div>

Legg til markdown="1" hvis boksen skal inneholde Markdown:

<div markdown="1" style="border-left: 4px solid #347dbe;
                         padding: 8px 14px; background-color: #f5f9fd;">

**Markdown fungerer her inne.**

- Du kan bruke lister og lenker.

</div>

Bruk span når bare noen få ord skal formateres: Dette er fremhevet tekst i en vanlig setning.

Dette er <span style="color: #2966a3; font-weight: 600;">fremhevet tekst</span>.

Vanlige HTML-elementer som fungerer fint i Markdown er div, span, strong, em, br, code, details, table, ul og ol. Unngå script og omfattende inline CSS i innholdssidene.

Ny eller endret tekst

Bruk grønn markering for å gjøre nytt innhold lett å finne under gjennomgang.

Ett avsnitt eller en overskrift

Dette avsnittet er nytt eller endret.

Dette avsnittet er nytt eller endret.
{: .new}

Legg {: .new} på linjen rett etter avsnittet eller overskriften.

Noen ord eller tekst i en tabell

Vanlig tekst, mens denne delen er ny.

Vanlig tekst, <span class="new">mens denne delen er ny.</span>

I Markdown-tabeller brukes samme span rundt innholdet i cellen:

| Dato | Endring |
|---|---|
| 11.08.26 | <span class="new">Ny forklaring lagt til.</span> |

En hel seksjon

<div class="new" markdown="1">

**Hele denne blokken er ny.**

- Den kan inneholde Markdown.

</div>

Utvidbart innhold

<details>
<summary>Vis flere detaljer</summary>
<div markdown="1">

Innhold skrevet med **Markdown**.

</div>
</details>

Bruk utvidbart innhold for detaljer som bare noen lesere trenger, ikke for informasjon alle må se.

Kommentarer og Liquid-eksempler

En Liquid-kommentar er synlig i .md-filen, men ikke på nettsiden:

{% comment %}
Forklar hvorfor denne løsningen er valgt.
{% endcomment %}

Jekyll prøver å kjøre Liquid selv inne i kodeblokker. Når du vil vise en include som kode, pakker du eksemplet i raw og endraw:

{% raw %}
```liquid
{% include note.html content="Dette vises som kode." %}
```
{% endraw %}

Sidebar med flere nivåer

Sidebar-filene har strukturen entries → folders → folderitems. Bruk subfolders når en side skal ha en ny mappe under seg:

entries:
- title: Sidebar
  levels: five
  folders:
  - title: sidebar tre
    output: web
    folderitems:
    - title: nivå 1
      url: /1.html
      output: web
      subfolders:
      - title: nivå 2
        output: web
        subfolderitems:
        - title: nivå 2
          url: /2.html
          output: web
          subfolders:
          - title: nivå 3
            output: web
            subfolderitems:
            - title: nivå 3
              url: /3.html
              output: web
              subfolders:
              - title: nivå 4
                output: web
                subfolderitems:
                - title: nivå 4
                  url: /4.html
                  output: web
                  subfolders:
                  - title: nivå 5
                    output: web
                    subfolderitems:
                    - title: nivå 5
                      url: /5.html
                      output: web

En sidebar kan også peke direkte til et annet nettsted eller et vedlegg:

- title: Ekstern API-dokumentasjon
  external_url: "https://example.com/api"
  output: web

YAML bruker mellomrom, ikke tabulator. Når du redigerer en eksisterende sidebar, legger du til elementet under riktig folders- eller folderitems-liste. Ikke opprett en ny entries-blokk.

Systemstatus

Statuswidgeten brukes for driftsstatus fra Digdir og Skatteetaten:

{% include status_widget.html
  api="https://status.digdir.no"
  title="Digitaliseringsdirektoratets systemstatus"
  priority_components="ID-porten,Maskinporten" %}

priority_components er valgfritt. Navnene må stemme med status-API-et. Flere innstillinger finnes i status-widget-dokumentasjon.md.

bundle exec jekyll build

For lokal forhåndsvisning kjører du:

bundle exec jekyll serve

Åpne deretter http://127.0.0.1:4000eller porten som er deafult for deg