From 1b8c16432ef251e7954165ec2325daf0996b1ed6 Mon Sep 17 00:00:00 2001 From: Michelle Purcell Date: Thu, 22 Dec 2022 17:23:15 +0000 Subject: [PATCH] WIP: Docs- Add landing page & URL redirect info Fix typo --- .../asciidoc/doc-contribute-docs-howto.adoc | 80 +++++++++++++++++-- 1 file changed, 72 insertions(+), 8 deletions(-) diff --git a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc index 3e057e24e7a06..2769efe40beec 100644 --- a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc +++ b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc @@ -4,34 +4,88 @@ and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// [id="doc-contribute-howto"] -= How to contribute documentation += Contribute to Quarkus documentation include::_attributes.adoc[] :categories: contributing :fn-diataxis: footnote:diataxis[Procida, D. Diátaxis documentation framework. https://diataxis.fr/] -Outline the recommended steps for making successful contributions to Quarkus documentation. +Outlines the recommended steps for successfully contributing to the Quarkus documentation. == Prerequisites -Quarkus docs use AsciiDoc, a lightweight markup language. +Quarkus docs are sourced in AsciiDoc, a lightweight markup language. We suggest you have the following materials nearby: - An editor or IDE that provides syntax highlighting and previews for AsciiDoc, either natively or with a plugin. - The https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc syntax reference] -- The xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference] for required syntax and other conventions. +- The xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference] for the required syntax, preferred style, and other conventions. -== Sources +== Locate the source files for Quarkus docs - AsciiDoc files are in the `src/main/asciidoc` directory within the `docs` module of the {quarkus-base-url}/tree/main/docs[Quarkus GitHub repository]. - Configuration documentation is generated from JavaDoc comments in Java source files. - Java, YAML, and other source files can also be xref:doc-reference.adoc#reference-source-code[referenced] by AsciiDoc files. +- The link:https://quarkus.io/guides/[Quarkus documentation] menu page, also known as the doc index page, is sourced in the link:https://github.com/quarkusio/quarkusio.github.io[quarkusio.github.io] repo. + + +== Create Quarkus content in AsciiDoc + +To ensure that your content shows up correctly on the link:https://quarkus.io/guides/[Quarkus documentation home page], use the following steps: + +. Decide on a content type that best fits the content that you are contributing. ++ +TIP: To help you decide, use the *Content types* section in xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference]. ++ +. Go to the `src/main/asciidoc/_templates` directory, and make a copy of the relevant template for the content type you have chosen. Be sure to: +** Use the filename syntax of`---.adoc`. For example, `security-basic-authentication-tutorial.adoc`. +** Save the new file to the `asciidoc` folder one level up. +. In header of the AsciiDoc file, set the ID to match the filename, and add at least one category as outlined in the templates and in the following example: ++ +[source,asciidoc] +---- +[id="security-basic-authentication-howto"] += Secure a Quarkus application with basic authentication +\include::_attributes.adoc[] +:categories: security +---- ++ +IMPORTANT: If you do not set the ID and category correctly, the content will not show up on the link:https://quarkus.io/guides/[Quarkus documentation home page]. ++ +For more information about the minimum AsciiDoc requirements, see xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference]. ++ +. Optional: If you have renamed the filename of an existing AsciiDoc file, see xref:doc-contribute-docs-howto#redirect-an-existing-Quarkus-AsciiDoc-file[Redirect an existing Quarkus AsciiDoc file]. + +== Redirect an existing Quarkus AsciiDoc file + +Occasionally, when content morphs, you might need to restructure an existing piece of Quarkus content. + +If you are renaming an existing Quarkus source doc file that has already been published to link:https://quarkus.io/guides/[Quarkus documentation], use the following steps to set up a redirect to ensure that the rename does not break bookmarks and other Quarkus-related docs that link to it. + +1. Go to the `_redirects/guides` directory in the link:https://github.com/quarkusio/quarkusio.github.io/tree/develop/_redirects/guides[quarkusio/quarkusio.github.io] repo. +2. Create a new markdown file in this directory that matches the original ID of the Quarkus doc file that you have just renamed, for example, `security-getting-started.md`. ++ +TIP: If you are not sure, what this should be, go to the original published doc or bookmark and copy the last part of the URL. ++ +3. Add the following contents to the empty markdown file: ++ +[source,markdown] +--- +permalink: /guides//index.html // <1> +newUrl: /guides/ // <2> +--- ++ +Where: +<1> Is the ID of the original asciidoc source file. +<2> Is the new ID that you have changed the original asciidoc source file to. + + == Preview and build Quarkus documentation AsciiDoc syntax highlighting and the preview provided by an IDE may be enough for minor documentation changes. -For significant changes or updates to generated configuration documentation, -you should build the `docs` module and view resulting output before submitting your changes for review. +When you make significant changes or updates to generated configuration documentation, +we recommend that you build the `docs` module locally, run the Vale linter as outlined below, and view resulting output before submitting your changes for review. include::{includes}/compile-quarkus-quickly.adoc[tag=quickly-install-docs] @@ -128,4 +182,14 @@ correcting the usage of a term, correcting a recurring error, or moving common c - If there are extensive code changes and documentation changes, create a separate PR for the documentation changes and include the relationship in the issue description. -Pull requests that contain changes to documentation will have the `area/documentation` label added automatically. \ No newline at end of file +Pull requests that contain changes to documentation will have the `area/documentation` label added automatically. + +== Automatic style checking on the PR diff + +The Vale linter automatically runs on all PRs that are submitted to the repo. +If the docs that you contribute do not align with the key style or terminology preferences of our Quarkus community, you will see a suggestion, warning, or error on the diff tab. +To ensure that your content gets approved, fix the errors that are flagged. + +We welcome your feedback on the Quarkus documentation style guidelines. + +If you disagree with the Vale results, be sure to add the yellow PR label `needs-vale-rule-tweak` and the doc SMEs will take a look. \ No newline at end of file