aktin / aktin/aktin-github-handbook

Rework AKTIN DWH User Documentation

オープン
#1 コメント 0 件 リアクション 0 件 担当者 3 名 @akomii が担当を希望しています GitHub で見る
documentation
主要言語
言語のデータがありません
スター
0
フォーク
0
PR マージ指標
30日以内にマージされた PR はありません

説明

## Goal

Replace the two existing user documentation sites of the AKTIN Data Warehouse (DWH) with one VuePress site in this repository, published on GitHub Pages.

Today the documentation lives in two repositories as Maven sites (`src/site/markdown/`) and is served from the AKTIN website:

- https://github.com/aktin/dwh-setup/tree/master/src/site/markdown (installation, updates, configuration, changelog)
- https://github.com/aktin/dwh-import/tree/main/src/site/markdown (import interfaces: CDA, HL7 FHIR, IHE XDS.b, demo server)

In addition, several how-to and troubleshooting articles exist only as Confluence exports (PDF and Markdown). All of this material has already been copied into `legacy/` (see #2).

## Result we want

- One site, one repository, one deploy pipeline.
- Content in German, in the style already used in `docs/install/` and `docs/update/`.
- Readers are DWH administrators at hospitals, not developers. Every page must be usable without reading source code.
- Site is reachable on GitHub Pages and is rebuilt automatically on every push to `main`.

## How to work in this repository

- All work happens on branch `dev`. Open a pull request against `main` when a sub-issue is finished. `main` is what gets deployed.
- Requirements: Node.js 22 and npm.
- Run `npm install` once, then `npm run docs:dev` starts a local server at http://localhost:8080 with hot reload.
- `npm run docs:build` produces the static site in `docs/.vuepress/dist/`. Run it before opening a pull request. Dead links and missing images show up as warnings there.
- Content lives in `docs//*.md`. Images belong next to the page in `docs//images/`.
- The sidebar is defined in `docs/.vuepress/config.js`. A new page only shows up after it is added there.
- Links used on many pages (support mail, links between pages) are defined once in `docs/.vuepress/_refs.md` and used as `[Text][ref-name]`.
- Version numbers come from `.env` and are used in Markdown as `{{ $theme.versions.dwh }}`. Never hardcode a DWH or Ubuntu version.
- Layout customisation (footer etc.) lives in `docs/.vuepress/layouts/Layout.vue`, which extends the default theme layout.

Background reading:
- VuePress guide https://vuejs.press/guide/
- default theme reference https://ecosystem.vuejs.press/themes/default/

コントリビューションガイド

このリポジトリのコントリビューションガイドは索引されていません

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。