The printing press of 2021 - using GitLab to publish the VSHN Handbook
0 likes•62 views
The document outlines a GitLab meetup presentation by VSHN's CTO detailing the development of their employee handbook using Git, Antora, and Asciidoctor. It covers the CI process for testing and deploying the handbook, as well as guidelines for local development and merge requests, making it accessible for non-engineers. Additionally, VSHN positions itself as a leading partner in DevOps, Kubernetes, and cloud operations in Switzerland.
The printing press of 2021 - using GitLab to publish the VSHN Handbook
- 1. 1 handbook.vshn.ch Gitlab Meetup 2021-09-16 Aarno Aukia, CTO
- 2. 2 Agenda ● About handbook.vshn.ch ● Gitlab CI process to test, build & deploy ● Local development ● Merge requests for non-engineers ● Publishing
- 3. ● The public VSHN employee handbook ● 2019-05-17 first commit ● 2019-07-25 first public version ● 1440 commits, 428 merge requests ● 134 web pages, 496 pages PDF https://handbook.vshn.ch 3
- 4. ● 10922 lines of AsciiDoc (similar to Markdown) ● Processed using Antora and AsciiDoctor ○ Result: HTML, PDF, EPUB, Manpage ○ Same setup used for 7 sites ● Git repo of handbook is not public because MR discussions are not public ● public: app catalog, managed services ● All tools are open source software Behind the scenes 4
- 8. ● Language style check: https://github.com/vshn/vale ● Antora: https://github.com/vshn/antora-docker ● VSHN template: https://github.com/vshn/antora-ui-default ● PDF: https://github.com/vshn/asciidoctor-pdf ● EPUB: https://github.com/vshn/asciidoctor-epub3 ● Full text indexer: https://github.com/vshn/antora-indexer-cli ● Production base image: https://github.com/vshn/antora-nginx ● Search base image: https://github.com/vshn/embedded-search-engine Links to tools 8
- 9. ● Work in a feature branch from “develop” ● make preview ○ auto-reloads on source edits at http://localhost:2020 using https://github.com/vshn/antora-preview ● make check ○ runs basic checks before commit/CI ● Create MR from feature branch to “develop” to review/discuss Local development 9
- 10. ● After some training, even non-engineers can comment, propose changes, and edit files in merge requests ● Demo: example MR for non-engineers 10
- 11. ● Complement Changelog since last release ● Create MR from develop to master ● Merge to master -> prod deployment ● Create template Changelog entry for next release Publishing 11
- 12. VSHN helps software developers to run their applications anywhere. 12
- 13. Thank you. https://vshn.ch/ VSHN is the leading Swiss partner for DevOps, Kubernetes & Cloud Operations. How can we help you? VSHN AG - Neugasse 10 - CH-8005 Zurich - Switzerland - +41 44 545 53 00 - https://vshn.ch/ - [email protected] 13