Address asciidoctor-dita-vale issues in Installing #4608

aneta-petrova · 2026-01-23T20:32:06Z

What changes are you introducing?

Various changes, including:

Adding the abstract role and creating basic abstracts
Changing some module types
Other small fixes to address asciidoctor-dita-vale rules

The most notable change is probably:

Modularizing the host registration snippet

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

To ensure a clean https://github.com/jhradilek/asciidoctor-dita-vale/ check for the guide.

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

N/A

Contributor checklists

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.17/Katello 4.19
Foreman 3.16/Katello 4.18 (Satellite 6.18; orcharhino 7.6)
Foreman 3.15/Katello 4.17
Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4; orcharhino 7.5)
Foreman 3.13/Katello 4.15 (EL9 only)
Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
We do not accept PRs for Foreman older than 3.12.

Split off a new module Move installer considerations to installer overview Merge two modules Move things around in the new merged module Change module type Update disconnected content with the same changes

The whole module is excluded for these builds.

github-actions · 2026-01-23T20:35:01Z

The PR preview for 5722664 is available at theforeman-foreman-documentation-preview-pr-4608.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

aneta-petrova · 2026-01-28T13:06:31Z

This is now ready for review.

I'm open to refining abstracts because some of them are completely new.

I also reworded some of the procedure steps (For example to add wording like "If you want to..." where I needed to remove block titles.) so I can revisit those too.

The other lines that show as new are just being moved from somewhere else. Especially considering that a new installation guide is coming, I don't think we need to spend that much time reviewing and adjusting those.

maximiliankolb

40/109

guides/common/modules/con_installing-project-server.adoc

guides/common/modules/con_performing-additional-configuration.adoc

guides/common/modules/con_using-activation-keys-for-host-registration.adoc

guides/common/modules/proc_adding-a-default-http-proxy-by-using-cli.adoc

guides/common/modules/proc_configuring-satellite-for-outgoing-emails.adoc

Co-authored-by: Maximilian Kolb <[email protected]>

maximiliankolb

70/110.

guides/common/assembly_configuring-satellite-with-an-http-proxy.adoc

guides/common/modules/con_configuring-smart-proxy-server-with-ssl-certificates.adoc

guides/common/assembly_installing-capsule-server.adoc

guides/common/assembly_basic-content-management-workflow.adoc

.../proc_resetting-custom-ssl-certificate-to-default-self-signed-certificate-on-smartproxy.adoc

guides/common/modules/proc_resetting-the-http-proxy-by-using-cli.adoc

guides/common/modules/proc_resetting-the-http-proxy-by-using-web-ui.adoc

guides/doc-Installing_Server/master.adoc

guides/doc-Installing_Server_Disconnected/master.adoc

maximiliankolb

91/110

guides/common/modules/con_installing-project-server.adoc

maximiliankolb · 2026-01-29T14:09:16Z

guides/common/modules/con_considerations-for-using-the-foreman-installer-utility.adoc

+
+[role="_abstract"]
+The {foreman-installer} utility is a collection of Puppet modules.
+Before using it to install {ProjectServer}, consider that installations can take tens of minutes and that repeated runs might overwrite manual configuration changes.


Suggested change

Before using it to install {ProjectServer}, consider that installations can take tens of minutes and that repeated runs might overwrite manual configuration changes.

IMO this only duplicates lines 10 and 13.

It does, but then line 7 is not enough for a proper abstract :/ The point was to summarize what users will read about in more detail in the module itself. Is that okay?

I am fine either way; this is not blocking your PR.

guides/common/modules/ref_prerequisites-for-registering-smart-proxy-to-project-server.adoc

guides/common/modules/proc_using-an-http-proxy-for-all-http-requests-by-using-web-ui.adoc

...ommon/modules/proc_configuring-server-to-consume-content-from-a-custom-cdn-by-using-cli.adoc

...dules/proc_configuring-projectserver-to-synchronize-content-over-a-network-by-using-cli.adoc

...ules/proc_configuring-projectserver-to-synchronize-content-through-exports-by-using-cli.adoc

Co-authored-by: Maximilian Kolb <[email protected]>

maximiliankolb

112/112.

maximiliankolb · 2026-01-30T07:37:08Z

guides/common/modules/ref_prerequisites-for-registering-smart-proxy-to-project-server.adoc

 For more information, see {InstallingSmartProxyDocURL}opening-required-ports[Opening required ports in _{InstallingSmartProxyDocTitle}_].
 endif::[]
-ifeval::["{context}" == "installing-capsule-server"]
+ifeval::["{context}" == "installing-{smart-proxy}-server"]


Suggested change

ifeval::["{context}" == "installing-{smart-proxy}-server"]

ifeval::["{context}" == "installing-{smart-proxy-context}-server"]

maximiliankolb · 2026-01-30T07:37:47Z

guides/common/modules/ref_prerequisites-for-registering-smart-proxy-to-project-server.adoc


-[id="Registering_Proxy_to_Server_{context}"]
-= Registering to {ProjectServer}
+[id="prerequisites-for-registering-{smart-proxy-context}-to-{project-context}-server"]


Suggested change

[id="prerequisites-for-registering-{smart-proxy-context}-to-{project-context}-server"]

[id="prerequisites-for-registering-{smart-proxy-context}-server-to-{project-context}-server"]

maximiliankolb · 2026-01-30T07:38:03Z

guides/common/modules/ref_prerequisites-for-registering-smart-proxy-to-project-server.adoc

I suggest to rename the file to guides/common/modules/ref_prerequisites-for-registering-smart-proxy-server-to-project-server.adoc

maximiliankolb · 2026-01-30T07:39:08Z

guides/common/modules/proc_using-an-http-proxy-for-all-http-requests-by-using-cli.adoc

+[role="_abstract"]
+If your {ProjectServer} must remain behind a firewall that blocks HTTP and HTTPS, you can configure an HTTP proxy for communication with external systems, including compute resources, by using Hammer CLI.
+
+Note that if you are using compute resources for provisioning, and you want to use a different HTTP proxy with the compute resources, the proxy that you set for all {Project} communication takes precedence over the proxies that you set for compute resources.


Suggested change

Note that if you are using compute resources for provisioning, and you want to use a different HTTP proxy with the compute resources, the proxy that you set for all {Project} communication takes precedence over the proxies that you set for compute resources.

Note that if you are using compute resources for provisioning, and you want to use a different HTTP proxy with the compute resources, the HTTP proxy that you set for all {Project} communication takes precedence over the HTTP proxies that you set for compute resources.

maximiliankolb · 2026-01-30T07:39:28Z

guides/common/modules/proc_using-an-http-proxy-for-all-http-requests-by-using-web-ui.adoc

+[role="_abstract"]
+If your {ProjectServer} must remain behind a firewall that blocks HTTP and HTTPS, you can configure an HTTP proxy for communication with external systems, including compute resources, by using the {ProjectWebUI}.

 Note that if you are using compute resources for provisioning, and you want to use a different HTTP proxy with the compute resources, the proxy that you set for all {Project} communication takes precedence over the proxies that you set for compute resources.


Suggested change

Note that if you are using compute resources for provisioning, and you want to use a different HTTP proxy with the compute resources, the proxy that you set for all {Project} communication takes precedence over the proxies that you set for compute resources.

Note that if you are using compute resources for provisioning, and you want to use a different HTTP proxy with the compute resources, the HTTP proxy that you set for all {Project} communication takes precedence over the HTTP proxies that you set for compute resources.

maximiliankolb · 2026-01-30T08:04:22Z

guides/common/modules/proc_adding-a-default-http-proxy-by-using-cli.adoc

+= Adding a default HTTP proxy by using Hammer CLI

+[role="_abstract"]
 If your network uses an HTTP Proxy, you can configure {ProjectServer} to use an HTTP proxy for requests to the Red{nbsp}Hat Content Delivery Network (CDN) or another content source.


Suggested change

If your network uses an HTTP Proxy, you can configure {ProjectServer} to use an HTTP proxy for requests to the Red{nbsp}Hat Content Delivery Network (CDN) or another content source.

If your network uses an HTTP proxy, you can configure {ProjectServer} to use an HTTP proxy for requests to the Red{nbsp}Hat Content Delivery Network (CDN) or another content source.

maximiliankolb · 2026-01-30T08:04:43Z

guides/common/modules/proc_adding-a-default-http-proxy-by-using-web-ui.adoc

+= Adding a default HTTP proxy by using {ProjectWebUI}
+
+[role="_abstract"]
+If your network uses an HTTP Proxy, you can configure {ProjectServer} to use an HTTP proxy for requests to the Red{nbsp}Hat Content Delivery Network (CDN) or another content source.


Suggested change

If your network uses an HTTP Proxy, you can configure {ProjectServer} to use an HTTP proxy for requests to the Red{nbsp}Hat Content Delivery Network (CDN) or another content source.

If your network uses an HTTP proxy, you can configure {ProjectServer} to use an HTTP proxy for requests to the Red{nbsp}Hat Content Delivery Network (CDN) or another content source.

maximiliankolb · 2026-01-30T08:09:59Z

guides/common/modules/proc_adding-hosts-to-a-freeipa-host-group.adoc

+{ProjectName}'s realm feature provides administrators with the ability to map the {ProjectName} host groups to the {FreeIPA} parameter `userclass` which allow administrators to configure automembership.
+
+When nested host groups are used, they are sent to the {FreeIPA} server as they are displayed in the {ProjectName} User Interface.
+For example, "Parent/Child/Child".


Suggested change

For example, "Parent/Child/Child".

For example, `Parent/Child/Child`.

maximiliankolb · 2026-01-30T08:11:54Z

.../common/modules/proc_configuring-hosts-to-use-an-alternate-cname-for-content-management.adoc

+Perform these steps on the hosts you want to configure.

+.Procedure
+. If you want to configure the host with the bootstrap script, run the bootstrap script with the `--server _My-Alternate-FQDN.example.com_` option to register the host to the alternate {Project} CNAME:


You could also make this an unordered list ine lin 14 and 20 because the user will only pick one of the other, not both in sequence.

maximiliankolb · 2026-01-30T08:28:32Z

...on/modules/proc_configuring-projectserver-or-smartproxyserver-for-freeipa-realm-support.adoc

+= Configuring {ProjectServer} or {SmartProxyServer} for {FreeIPA} realm support
+
+[role="_abstract"]
+Complete the following procedure on {Project} and every {SmartProxy} that you want to use:


Suggested change

Complete the following procedure on {Project} and every {SmartProxy} that you want to use:

Complete the following procedure on your {ProjectServer} and every {SmartProxyServer} that you want to use.

aneta-petrova added 25 commits January 22, 2026 10:26

Add abstracts

91ece23

Minor fixes

dc88a86

Consolidate installer considerations and procedures

968608e

Split off a new module Move installer considerations to installer overview Merge two modules Move things around in the new merged module Change module type Update disconnected content with the same changes

Consolidate server install introductions into a single module

76a608a

Add abstracts

cd30156

Split a section into its own module

b8885fe

Split module into web UI and CLI

50c6b04

Split a module into web UI and CLI

8b1b59f

Split a module into web UI and CLI

5afcf9e

Split a module into web UI and CLI

128a48f

Modularize an assembly

ce501fd

Drop an unnecessary prerequisite

05b44c5

Remove block titles

fe09feb

Change module type

12e074d

Add missing anchor

8de6aa9

Break a prerequisite into a separate procedure

a389f0c

Drop a prereq for f-el and f-deb

0402462

The whole module is excluded for these builds.

Drop an obsolete link

b70b233

Split a module into web UI and CLI

88cc583

Split module into web UI and CLI

be13e0d

Split module into web UI and CLI

d09e6b7

Drop 'by using' from a heading to avoid duplication

501f34a

Split two modules into web UI and CLI

a48290f

Add content type

c89f7de

Minor fixes

01e9398

pr-processor bot added the Not yet reviewed label Jan 23, 2026

github-actions bot added Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective Needs testing Requires functional testing labels Jan 23, 2026

aneta-petrova force-pushed the dita-installing branch from de47ec2 to 3142172 Compare January 23, 2026 20:42

aneta-petrova removed Needs tech review Requires a review from the technical perspective Needs testing Requires functional testing labels Jan 23, 2026

aneta-petrova added 2 commits January 23, 2026 21:47

Remove unused module

f5ba78e

Move installer considerations

36464f0

aneta-petrova marked this pull request as ready for review January 28, 2026 13:05

aneta-petrova added style review done No issues from docs style/grammar perspective and removed Needs style review Requires a review from docs style/grammar perspective labels Jan 28, 2026

maximiliankolb self-requested a review January 28, 2026 13:12

maximiliankolb reviewed Jan 28, 2026

View reviewed changes

pr-processor bot removed the Not yet reviewed label Jan 28, 2026

aneta-petrova added Needs style review Requires a review from docs style/grammar perspective and removed style review done No issues from docs style/grammar perspective labels Jan 28, 2026

aneta-petrova force-pushed the dita-installing branch from 2f0e0a3 to 7fbb475 Compare January 29, 2026 12:22

Apply suggestions from style review

a22e443

Co-authored-by: Maximilian Kolb <[email protected]>

aneta-petrova force-pushed the dita-installing branch from 7b89847 to a22e443 Compare January 29, 2026 12:24

maximiliankolb reviewed Jan 29, 2026

View reviewed changes

Apply easy fixes from style review

14ef6a6

Co-authored-by: Maximilian Kolb <[email protected]>

aneta-petrova force-pushed the dita-installing branch from 4ccd294 to 14ef6a6 Compare January 29, 2026 20:11

aneta-petrova and others added 5 commits January 29, 2026 21:16

Apply easy fix from style review

af98c91

Co-authored-by: Maximilian Kolb <[email protected]>

Move intro to concept file

f7c58b1

Add blank lines

43d5891

Move intro to a concept file

f23274d

Add blank lines

3c910a8

aneta-petrova force-pushed the dita-installing branch from 301290f to 3c910a8 Compare January 29, 2026 20:31

Apply suggestion from style review

5722664

aneta-petrova mentioned this pull request Jan 29, 2026

Review code block in sync over network procedure #4625

Open

maximiliankolb reviewed Jan 30, 2026

View reviewed changes

	ifeval::["{context}" == "installing-{smart-proxy}-server"]
	ifeval::["{context}" == "installing-{smart-proxy-context}-server"]

	[id="prerequisites-for-registering-{smart-proxy-context}-to-{project-context}-server"]
	[id="prerequisites-for-registering-{smart-proxy-context}-server-to-{project-context}-server"]

	Note that if you are using compute resources for provisioning, and you want to use a different HTTP proxy with the compute resources, the proxy that you set for all {Project} communication takes precedence over the proxies that you set for compute resources.
	Note that if you are using compute resources for provisioning, and you want to use a different HTTP proxy with the compute resources, the HTTP proxy that you set for all {Project} communication takes precedence over the HTTP proxies that you set for compute resources.

	If your network uses an HTTP Proxy, you can configure {ProjectServer} to use an HTTP proxy for requests to the Red{nbsp}Hat Content Delivery Network (CDN) or another content source.
	If your network uses an HTTP proxy, you can configure {ProjectServer} to use an HTTP proxy for requests to the Red{nbsp}Hat Content Delivery Network (CDN) or another content source.

	For example, "Parent/Child/Child".
	For example, `Parent/Child/Child`.

	Complete the following procedure on {Project} and every {SmartProxy} that you want to use:
	Complete the following procedure on your {ProjectServer} and every {SmartProxyServer} that you want to use.

Address asciidoctor-dita-vale issues in Installing #4608

Are you sure you want to change the base?

Address asciidoctor-dita-vale issues in Installing #4608

Uh oh!

Conversation

aneta-petrova commented Jan 23, 2026

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Contributor checklists

Uh oh!

github-actions bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aneta-petrova commented Jan 28, 2026

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

github-actions bot commented Jan 23, 2026 •

edited

Loading