Skip to content

Commit fc4d952

Browse files
committed
updates to the mod docs guide
1 parent 5f2ac83 commit fc4d952

File tree

4 files changed

+36
-38
lines changed

4 files changed

+36
-38
lines changed

mod_docs_guide/getting-started-modular-docs-ocp.adoc

Lines changed: 8 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
// This assembly is included in the following assemblies:
2-
//
3-
// NONE
4-
51
// Base the file name and the ID on the assembly title. For example:
62
// * file name: my-assembly-a.adoc
73
// * ID: [id='my-assembly-a']
@@ -10,23 +6,24 @@
106
// Choose a context that is not too long and encapsulates what this assembly or
117
// module is about. Context MUST be unique.
128

9+
[id='getting-started-modular-docs-ocp']
10+
= Getting started with modular docs on OpenShift
11+
include::modules/common-attributes.adoc[]
1312
:context: assembly-gsg
14-
15-
[id='getting-started-modular-docs-ose-{context}']
16-
= Getting Started with Modular Docs on OpenShift
13+
toc::[]
1714

1815
This is the modular docs getting started guide for the OpenShift documentation
1916
team and anyone who might be contributing content to it.
2017

2118
This guide itself has been written using the format of the modular docs
2219
initiative.
2320

24-
[id='prerequisites_{context}']
25-
== Prerequisites
21+
.Prerequisites
2622

2723
* You have read through and familiarized yourself with the
28-
link:https://redhat-documentation.github.io/modular-docs[Red Hat CCS modular
29-
docs guide].
24+
link:https://redhat-documentation.github.io/modular-docs[Red Hat CCS modular docs guide].
25+
* You have reviewed
26+
xref:../mod_docs_guide/mod-docs-coventions-ocp.adoc#mod-docs-ocp-references[the Modular Docs OpenShift Conventions].
3027
* [Optional] You have received the modular docs training.
3128
* You know how to use Git.
3229

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
1-
// This assembly is included in the following assemblies:
2-
//
3-
// NONE
41

52
// Base the file name and the ID on the assembly title. For example:
63
// * file name: my-assembly-a.adoc
@@ -10,11 +7,13 @@
107
// Choose a context that is not too long and encapsulates what this assembly or
118
// module is about. Context MUST be unique.
129

10+
[id='mod-docs-ocp-references']
11+
= Modular docs OpenShift conventions
12+
include::modules/common-attributes.adoc[]
1313
:context: assembly-ocp-conventions
14+
toc::[]
1415

15-
[id='mod-docs-ocp-references_{context}']
16-
= Modular Docs OpenShift Conventions
17-
18-
This is the modular docs conventions guide for contributing to OpenShift docs.
16+
Before you contribute to the OpenShift docs, review the following modular docs
17+
conventions.
1918

2019
include::modules/mod-docs-ocp-conventions.adoc[leveloffset=+1]

modules/creating-your-first-content.adoc

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,19 @@
77
// * ID: [id='doing-procedure-a']
88
// * Title: = Doing procedure A
99

10-
[id='creating-your-first-content_{context}']
11-
= Creating Your First Content
10+
[id='creating-your-first-content-{context}']
11+
= Creating your first content
1212

1313
In this procedure, you will create your first example content using modular
1414
docs for the OpenShift docs repository.
1515

16-
[discrete]
17-
== Prerequisites
16+
.Prerequisites
1817

1918
* You have forked and then cloned the OpenShift docs repository locally.
2019
* You have downloaded and are using Atom text editor for creating content.
2120
* You have installed AsciiBinder (the build tool for OpenShift docs).
2221

23-
[discrete]
24-
== Procedure
22+
.Procedure
2523

2624
. Navigate to your locally cloned OpenShift docs repository on a command line.
2725

@@ -64,7 +62,7 @@ in the comments. Give this assembly the title: `My First Assembly`.
6462
`:context: assembly-first-content`
6563

6664
. After the Prerequisites section, add the module created earlier (the following is
67-
deliberately spelled incorrectly to pass validation. Please use 'include' instead of 'ilude'):
65+
deliberately spelled incorrectly to pass validation. Use 'include' instead of 'ilude'):
6866

6967
+
7068
`ilude::modules/my-first-module.adoc[leveloffset=+1]`

modules/mod-docs-ocp-conventions.adoc

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
// Module included in the following assemblies:
22
//
3-
// assembly_mod-docs-reference-ocp.adoc
3+
// * mod_docs_guide/mod-docs-conventions-ocp.adoc
44

55
// Base the file name and the ID on the module title. For example:
66
// * file name: my-reference-a.adoc
77
// * ID: [id='my-reference-a']
88
// * Title: = My reference A
99

10-
[id='mod-docs-ocp-conventions_{context}']
11-
= Modular Docs OpenShift Conventions
10+
[id='mod-docs-ocp-conventions-{context}']
11+
= Modular docs OpenShift conventions
1212

1313
These Modular Docs conventions for OpenShift docs build on top of the CCS
1414
modular docs guidelines.
@@ -25,7 +25,7 @@ IMPORTANT: If some convention is duplicated, the convention in this guide
2525
supersedes all others.
2626

2727
[id='ocp-ccs-conventions-{context}']
28-
== OpenShift CCS Conventions
28+
== OpenShift CCS conventions
2929

3030
* All assemblies must define a context that is unique.
3131
+
@@ -40,15 +40,15 @@ Example:
4040
* All anchor ids must follow the format:
4141
+
4242
----
43-
[id='<anchor-name-with-dashes>_{context}']
43+
[id='<anchor-name-with-dashes>-{context}']
4444
----
4545
+
46-
Anchor name is _connected_ to the `&#123;context&#125;` using an underscore.
46+
Anchor name is _connected_ to the `&#123;context&#125;` using a dash.
4747
+
4848
Example:
4949
+
5050
----
51-
[id='creating-your-first-content_{context}']
51+
[id='creating-your-first-content-{context}']
5252
----
5353

5454
* All modules anchor ids must have the `&#123;context&#125;` variable.
@@ -75,7 +75,7 @@ Example comment section in a module:
7575
----
7676
// Module included in the following assemblies:
7777
//
78-
// assembly_getting-started-modular-docs-ocp.adoc
78+
// mod_docs_guide/mod-docs-conventions-ocp.adoc
7979
----
8080

8181
* All modules must go in the modules directory which is present in the top level
@@ -85,16 +85,18 @@ link:https://redhat-documentation.github.io/modular-docs/[modular docs guideline
8585

8686
* All assemblies must go in the the relevant guide/book (MORE TO COME ON THIS).
8787

88-
* In your modules, when you are linking to the content in other books, you must
88+
* In your assemblies, when you are linking to the content in other books, you must
8989
use the relative path starting like so:
9090
+
9191
----
92-
xref: ../architecture/additional_concepts/authorization.adoc#roles[default roles] are here.
92+
xref:../architecture/architecture.adoc#architecture[architecture] overview.
9393
----
9494
+
95-
All xref links that are placed in the modules in the modules folder must begin
96-
with `../` as you are navigating into the root folder and then into the actual
97-
book/assembly.
95+
[IMPORTANT]
96+
====
97+
You must not include xrefs in modules or create an xref to a module. You can
98+
only use xrefs to link from one assembly to another.
99+
====
98100

99101
* All modules in assemblies must be included using the following format (please replace 'ilude' with 'include'):
100102
+
@@ -112,6 +114,7 @@ Example:
112114

113115
NOTE: There is no `..` at the starting of the path.
114116

117+
////
115118
* If your assembly is in a subfolder of a guide/book directory, you must add a
116119
statement to the assembly’s metadata to use `relfileprefix`.
117120
+
@@ -136,6 +139,7 @@ module remains the same as described in the previous bullet.
136139
+
137140
NOTE: This strategy is in place so that links resolve correctly on both
138141
docs.openshift.com and portal docs.
142+
////
139143

140144
* Do not use 3rd level folders even though AsciiBinder permits it. If you need
141145
to, work out a better way to organize your content.

0 commit comments

Comments
 (0)