https://github.com/outscale/osc-doc-framework

osc-doc-framework is a framework used to generate OUTSCALE documentations
https://github.com/outscale/osc-doc-framework

Last synced: 7 days ago
JSON representation

osc-doc-framework is a framework used to generate OUTSCALE documentations

• Host: GitHub
• URL: https://github.com/outscale/osc-doc-framework
• Owner: outscale
• License: mpl-2.0
• Created: 2023-06-02T13:54:00.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-04-11T12:30:04.000Z (7 months ago)
• Last Synced: 2024-04-11T13:46:23.064Z (7 months ago)
• Language: JavaScript
• Homepage:
• Size: 1.7 MB
• Stars: 2
• Watchers: 7
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE

Awesome Lists containing this project

README

        
= osc-doc-framework

image:https://docs.outscale.com/fr/userguide/_images/Project-Graduated-green.svg[Project Graduated, link="https://docs.outscale.com/en/userguide/Open-Source-Projects.html"]

`osc-doc-framework` is a framework used to generate OUTSCALE documentations. It is primarily based on the https://antora.org/[Antora] documentation site generator, with extension and theme files to customize the Antora output.

== Prerequisites

* You need to install `node` 20.0.0 or later from the https://nodejs.org/en/[official Node.js website] or via the https://github.com/nvm-sh/nvm[Node Version Manager (`nvm`)].

* You need to create an Antora documentation project. For more information, see the https://docs.antora.org/antora/latest/[official Antora documentation].

== Installing

There are multiple ways to install `osc-doc-framework` in your Antora documentation project. Here is an example:

[source,shell]

----

$ cd 

$ git clone https://github.com/outscale/osc-doc-framework.git

$ npm install ./osc-doc-framework

----

Then, in your Antora playbook file, you can plug the different components of `osc-doc-framework` by adding the following keys:

[source,yaml]

----

ui:

  bundle:

    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable

  supplemental_files: ./node_modules/@outscale/osc-doc-framework/antora-theme

antora:

  extensions:

    - require: ./node_modules/@antora/lunr-extension

    - require: ./node_modules/@outscale/osc-doc-framework/antora-special-pages-extension

    - require: ./node_modules/antora-navigator-extension

    - require: ./node_modules/@outscale/osc-doc-framework/antora-extension

    - require: ./node_modules/@outscale/osc-doc-framework/antora-rss-extension

----

== Linting

Optionally, you can configure your Git to use the pre-commit hook in the `git-hooks` folder. This pre-commit hook will run https://vale.sh/[Vale] on your documentation pages in order to lint them with the style rules located in the `Vale/styles` folder.

== Building

Once you have installed `osc-doc-framework`, you can build your documentation in the usual Antora way:

[source,shell]

----

$ npx antora 

----

== Contributing

Feel free to open an issue in case of bugs.

== License

Copyright Outscale SAS

MPL-2.0