README
Jobbhåndbok for Variant
Jobbhåndbok for Variant som er i kontinuerlig utvikling og forbedring. Tilgjengelig som Markdown via NPM, i Terminalen, eller kanskje først og fremst på nettsiden: https://handbook.variant.no.
Har du spørsmål, kommentarer eller forbedringer til teksten? Send inn en Pull Request, da!
Installering via NPM
Tilgjengelig som data og i terminalen!
I terminalen
Du kan lese om Variant fra terminalen:
npm i -g @variant/handbook
# Installerer...
# Kjør:
variant -h
# Viser hjelpetekst.
# Kjør:
variant
# Gir oversikt over seksjoner du kan lese
Som markdown data
npm install @variant/handbook
Foreløpig ganske spartansk dokumentasjon, men det kommer seg.
const variant = require("@variant/handbook");
variant.getPage("handbook").then(function(data) {
console.log(data.output);
// data is of format:
// {
// modified: Date, // When page last changed
// toc: Array<ToC>, // Overview of table of contents
// raw: string, // Raw markdown
// output: string // Parsed markdown in ansi colors
// }
// ToC Object format:
// {
// content: string, // Title. Use this in getSection
// level: number, // level of heading (1-6)
// }
});
variant.pages().then(async function(pages) {
// pages is of type Array<string>
const page = await variant.getPage(pages[1]);
// Gets rendered ansi markdown of the second section of second page
const markdownOfSection = variant.getSection(page.toc[1]);
});
Oppsett av prosjekt lokalt
Dersom man skal deploye oppdateringer av håndboken selv forutsettes det at man har Node.js istallert. Når man installerer Node.js får man også med NPM som pakkehåndterer. Fra root av dette repoet, må man installere alle avhengigheter:
npm install
Lag ny versjon av nettsiden
Nå ligger sammensydde filene ute under docs/
. Dette er en mappe som blir
konstruert når man bygger på nytt. Kildekodene ligger under src/
, og statiske
filer som skal med (f.eks bilder, styles, JavaScript osv) legges under
src/static/
.
Når man har endret innhold, layout eller statiske filer kan man bygge en ny versjon via terminalen:
npm run build
Dette vil generere og kopiere over alle filer til docs/
og gjøre at du har
unstaged changes i git. Stage, commit og push disse og det vil automatisk
publiseres på nettsiden.
Når vi gjør flere endringer er det enklere å lytte på filendringer for å bygge:
npm run watch
Kjør siden lokalt
For å teste URL-er er det alltid bedre å kjøre en HTTP-tjener. Dette kreves og for å teste service workers. For å kjøre en lokal test server kjør følgende kommando i terminalen:
npm start
Automatisk deploy av nettside og NPM modul
Det er satt opp kontinuerlig bygging av siden og NPM-modulen. Håndboken blir hostet via gh-pages i varianter/handbook-host og blir bygget av Travis CI.
Nettsiden blir deployet for hver gang master blir endret, men NPM-modul blir kun deployet hver gang en ny Git tag blir lagt til.
Legge til ny git tag
Tenk på versjonering av NPM-modul. Er det brekkende endring? major
. Er det Ny
feature? minor
. Er det bare tekstendringer? patch
. For å bumpe versjon og
lage ny tag kan man bruke mversion
som dette:
npx mversion patch -m
Hvor patch
kan være major
, minor
eller patch
.
Dette vil sette ny versjon i package.json
og lage en annotert git tag. For å
pushe det ut på Github brukes følgende kommando:
git push && git push --tags
Dette vil pushe både vanlig commits og den nye tag-en. Dersom det er API-endringer, husk å dokumenter det i releases som changelog.