https://github.com/appuio/appuio-cloud-docs

APPUiO Cloud User Documentation
https://github.com/appuio/appuio-cloud-docs

antora appuio appuio-cloud asciidoc documentation hacktoberfest vshn-project-apub

Last synced: 4 days ago
JSON representation

APPUiO Cloud User Documentation

• Host: GitHub
• URL: https://github.com/appuio/appuio-cloud-docs
• Owner: appuio
• License: cc-by-sa-4.0
• Created: 2021-09-17T06:30:00.000Z (over 3 years ago)
• Default Branch: master
• Last Pushed: 2024-12-31T09:43:49.000Z (7 days ago)
• Last Synced: 2024-12-31T10:17:41.249Z (7 days ago)
• Topics: antora, appuio, appuio-cloud, asciidoc, documentation, hacktoberfest, vshn-project-apub
• Language: Makefile
• Homepage: https://docs.appuio.cloud
• Size: 8.99 MB
• Stars: 0
• Watchers: 13
• Forks: 2
• Open Issues: 4
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE

Awesome Lists containing this project

README

        
= APPUiO Cloud :: Documentation for Users

This repository contains all the content hosted at https://docs.appuio.cloud/.

The content is written in https://asciidoctor.org/docs/what-is-asciidoc/[AsciiDoc] and rendered using https://docs.antora.org/[Antora].

Building and deployment happens on a https://git.vshn.net/appuio-public/appuio-cloud-docs-antora-pipeline[GitLab CI/CD Pipeline].

It is hosted on APPUiO Cloud.

[TIP]

====

* Writing AsciiDoc is best done using Visual Studio Code with https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[the AsciiDoc addon].

* For a reference what you can do with AsciiDoc, have a look at https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc Writer’s Guide].

* Antora is capable of doing many great things with documentation. See https://docs.antora.org/[the Antora docs] to gain insights into the tooling.

====

== Documentation structure

The documentation structure is inspired by the https://documentation.divio.com/[Divio's documentation structure]:

Tutorials (Learning-oriented):: A lesson which teaches you something.

Location: `docs/modules/ROOT/pages/tutorials`.

How-to guides (Problem-oriented):: Step-by-step guides to achieve a goal. Location: `docs/modules/ROOT/pages/how-to`.

Technical reference (Information-oriented):: Description about the inner ongoings. Location: `docs/modules/ROOT/pages/references`.

Explanation (Understanding-oriented):: Explains the background. Location: `docs/modules/ROOT/pages/explanations`.

== Contributing

Create a new branch to make the changes. After you're satisfied with the changes open a Pull Request against the `master` branch.

=== Previewing Changes

To preview your changes locally, make sure you have Docker or Podman installed.

Just type `make preview` and open your browser at http://localhost:2020. This even provides support for live reload when working on the content. See https://github.com/vshn/antora-preview#livereload[this documentation] for more information about it.

=== Adding a New Page

. Create new AsciiDoc (`.adoc`) file in the best matching folder according to the described structure under `docs/modules/ROOT/pages/`.

. Add the file to the navigation under `docs/modules/ROOT/`

For removing pages just do the opposite: Remove the file and remove the entry in the navigation.

== Deployment

This repository only holds https://docs.antora.org/antora/2.3/standard-directories/[Antora content], no plumbing and tooling (aka the Antora https://docs.antora.org/antora/2.3/run-antora/[`playbook.yml`] and `Dockerfile`) to build and deploy it.

All pushes to the `master` branch trigger a GitHub action (`.github/worflows/triggerci.yml`) which in turn triggers the https://git.vshn.net/vshn/docs/kb/-/blob/master/.gitlab-ci.yml[GitLab CI job] to build and deploy the content using Antora.