Skip to content

Commit c9d375c

Browse files
yaacovyaacov
committed
chore(ci): migrate upstream site to just-the-docs theme
Replace jekyll-theme-cayman with just-the-docs for improved navigation, search, and maintainability of the upstream Forklift documentation site. Resolves: none Co-authored-by: AI Assistant <ai-assistant@noreply.redhat.com> Signed-off-by: yaacov <kobi.zamir@gmail.com>
1 parent 27b8a92 commit c9d375c

File tree

28 files changed

+629
-1893
lines changed

28 files changed

+629
-1893
lines changed

‎.cursor/skills/upstream-downstream/SKILL.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
name: upstream-downstream
3+
description: Guide for using upstream and downstream variables and conditional content in AsciiDoc modules. Use when writing, editing, or reviewing .adoc files, when using product names, CLI commands, namespaces, or operator names in documentation, or when adding build-specific content for upstream (Forklift) vs downstream (MTV).
4+
---
5+
6+
# Upstream & Downstream Authoring
7+
8+
## Golden Rule
9+
10+
Never hardcode a product name, CLI tool, namespace, or operator name. Always use the corresponding variable.
11+
12+
## Variable Definitions
13+
14+
Downstream values live in `documentation/modules/common-attributes.adoc`.
15+
Upstream overrides live in `_config.yml` under `asciidoctor.attributes`.
16+
17+
Upstream builds load `common-attributes.adoc` first, then `_config.yml` overrides. Any variable **not** overridden in `_config.yml` leaks the downstream value into upstream.
18+
19+
## Variable Quick Reference
20+
21+
| Variable | Upstream (Forklift) | Downstream (MTV) |
22+
|---|---|---|
23+
| `{build}` | upstream | downstream |
24+
| `{project-full}` | Forklift | Migration Toolkit for Virtualization |
25+
| `{project-short}` | Forklift | MTV |
26+
| `{project-first}` | Forklift | Migration Toolkit for Virtualization (MTV) |
27+
| `{virt}` | KubeVirt | OpenShift Virtualization |
28+
| `{a-virt}` | a KubeVirt | an OpenShift Virtualization |
29+
| `{ocp}` | OKD | Red Hat OpenShift |
30+
| `{ocp-short}` | OKD | OpenShift |
31+
| `{oc}` | kubectl | oc |
32+
| `{namespace}` | konveyor-forklift | openshift-mtv |
33+
| `{operator}` | forklift-operator | mtv-operator |
34+
| `{operator-name}` | Forklift Operator | MTV Operator |
35+
| `{rhv-full}` | oVirt | Red Hat Virtualization |
36+
| `{rhv-short}` | oVirt | RHV |
37+
| `{a-rhv}` | an oVirt | a Red Hat Virtualization |
38+
| `{manager}` | Engine | Manager |
39+
| `{must-gather}` | quay.io/kubev2v/forklift-must-gather:latest | registry.redhat.io/.../mtv-must-gather-rhel8:{project-z-version} |
40+
| `{vmw}` | *(not overridden)* | VMware |
41+
42+
### Downstream-only variables (no upstream override)
43+
44+
These exist only in `common-attributes.adoc` and are safe to use inside `ifeval::["{build}" == "downstream"]` blocks:
45+
46+
- `{operator-name-ui}` — Migration Toolkit for Virtualization Operator
47+
- `{ocp-name}` — OpenShift
48+
- `{ocp-version}` — e.g. 4.21
49+
- `{ocp-doc}` — link prefix to Red Hat OCP docs
50+
- `{project-version}` — e.g. 2.11
51+
- `{project-z-version}` — e.g. 2.11.0
52+
- `{mtv-plan}`, `{mtv-mig}` — Red Hat doc URLs
53+
54+
## Conditional Content
55+
56+
### Build-based conditionals (`ifeval`)
57+
58+
Use `ifeval` to show content only in one build:
59+
60+
```asciidoc
61+
ifeval::["{build}" == "upstream"]
62+
This sentence appears only in the Forklift (upstream) docs.
63+
endif::[]
64+
65+
ifeval::["{build}" == "downstream"]
66+
This sentence appears only in the MTV (downstream) docs.
67+
endif::[]
68+
```
69+
70+
**Critical syntax note:** The variable must be wrapped in curly braces — `"{build}"`, not `"build"`. Without braces the condition compares a literal string and silently never matches.
71+
72+
### Provider-specific conditionals (`ifdef`)
73+
74+
Modules reused across providers use `ifdef` guards. The attribute is set by the parent assembly via `:context:`.
75+
76+
Provider attributes: `vmware`, `rhv`, `ova`, `ostack`, `cnv`
77+
78+
```asciidoc
79+
ifdef::vmware[]
80+
= Adding a {vmw} vSphere source provider
81+
endif::[]
82+
ifdef::rhv[]
83+
= Adding {a-rhv} source provider
84+
endif::[]
85+
```
86+
87+
### UI vs CLI conditionals
88+
89+
```asciidoc
90+
ifdef::web[]
91+
. In the {ocp-short} web console, navigate to *Migration* > *Plans*.
92+
endif::[]
93+
ifdef::cli[]
94+
. Run `{oc} get plans -n {namespace}`.
95+
endif::[]
96+
```
97+
98+
### Context management in assemblies
99+
100+
Assemblies must save and restore `:context:` so nested includes don't clobber each other:
101+
102+
```asciidoc
103+
ifdef::context[:parent-context: {context}]
104+
:context: vmware
105+
106+
\include::modules/adding-source-provider.adoc[leveloffset=+1]
107+
108+
ifdef::parent-context[:context: {parent-context}]
109+
ifndef::parent-context[:!context:]
110+
```
111+
112+
## Variables in Code Blocks
113+
114+
Variables are **not** expanded inside literal blocks by default. Add the `subs` attribute:
115+
116+
```asciidoc
117+
[source,terminal,subs="attributes+"]
118+
----
119+
$ {oc} get pods -n {namespace}
120+
----
121+
```
122+
123+
For combined substitutions:
124+
125+
```asciidoc
126+
[options="nowrap" subs="+quotes,+attributes"]
127+
----
128+
$ {oc} get migration -n {namespace}
129+
----
130+
```
131+
132+
## Common Pitfalls
133+
134+
1. **"Red Hat {virt}"** — renders as "Red Hat KubeVirt" upstream. Wrap in a build conditional or use a dedicated variable.
135+
2. **Downstream-only variables in shared content** — if a variable has no upstream override (e.g. `{vmw}`), using it outside a downstream guard produces unexpected output upstream.
136+
3. **Forgetting `subs="attributes+"`** — variables appear as literal `{oc}` in code blocks without it.
137+
4. **Missing braces in `ifeval`** — `ifeval::["build" == "upstream"]` is always false; correct form is `ifeval::["{build}" == "upstream"]`.
138+
5. **Hardcoded "oc" or "kubectl"** — always use `{oc}` so the right CLI tool renders per build.
139+
6. **Hardcoded namespace** — always use `{namespace}` instead of writing `openshift-mtv` or `konveyor-forklift`.
140+
141+
## Module ID Convention
142+
143+
Module IDs must include the `{context}` suffix so the same module can be included in multiple contexts without ID collision:
144+
145+
```asciidoc
146+
[id="adding-source-provider_{context}"]
147+
= Adding a source provider
148+
```

‎.jekyll-cache/Jekyll/Cache/Jekyll--Cache/b7/9606fb3afea5bd1609ed40b622142f1c98125abcfe89a76a661b0e8e343910‎

2.71 KB
Binary file not shown.

‎Gemfile‎

Lines changed: 9 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,17 @@
11
# frozen_string_literal: true
2-
# Encoding.default_external = Encoding::UTF_8
3-
# Encoding.default_internal = Encoding::UTF_8
42

53
source "https://rubygems.org"
64

7-
# gem "asciidoctor-pdf"
8-
gem "asciidoctor"
9-
# gem "bundle"
10-
# gem "html-proofer"
11-
# gem "jekyll-theme-minimal"
12-
# gem "jekyll-feed"
13-
gem "jekyll-paginate"
14-
# gem "jekyll-redirect-from"
15-
# gem "jekyll-sitemap"
16-
# gem "jekyll-tagging"
17-
# gem 'jekyll-seo-tag'
18-
# gem "jekyll", ">= 3.5"
19-
# gem "premonition", ">= 4.0.0"
20-
# gem "pygments.rb"
21-
# gem "rake"
22-
#
23-
#
24-
gem "github-pages", group: :jekyll_plugins
5+
gem "jekyll", "~> 4.3"
6+
gem "just-the-docs", "~> 0.10"
257

26-
# ensures that jekyll-asciidoc is loaded first
278
group :jekyll_plugins do
28-
gem 'jekyll-asciidoc'
9+
gem "jekyll-asciidoc"
10+
gem "jekyll-seo-tag"
11+
gem "jekyll-sitemap"
12+
gem "jekyll-redirect-from"
13+
gem "jekyll-feed"
14+
gem "jekyll-include-cache"
2915
end
3016

31-
gemspec
17+
gem "asciidoctor"

0 commit comments

Comments
 (0)