creating-your-first-content.adoc

Creating your first content

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

Prerequisites

• You have forked and then cloned the OpenShift docs repository locally.

• You have downloaded and are using Atom text editor for creating content.

• You have installed AsciiBinder (the build tool for OpenShift docs).

Procedure

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

2. Create a new feature branch:

   git checkout master
   git checkout -b my_first_mod_docs

3. If there is no modules directory in the root folder, create one.

4. In this modules directory, create a file called my-first-module.adoc.

5. Open this newly created file in Atom and copy into this file the contents from the procedure template from Modular docs repository.

6. Replace the content in this file with some example text using the guidelines in the comments. Give this module the title My First Module. Save this file. You have just created your first module.

7. Create a new directory from the root of your OpenShift docs repository and call it my_guide.

8. In this my_guide directory, create a new file called assembly_my-first-assembly.adoc.

9. Open this newly created file in Atom and copy into this file the contents from the assembly template from Modular docs repository.

10. Replace the content in this file with some example text using the guidelines in the comments. Give this assembly the title: My First Assembly.

11. Before the first anchor id in this assembly file, add a :context: attribute:

    :context: assembly-first-content

12. After the Prerequisites section, add the module created earlier (the following is deliberately spelled incorrectly to pass validation. Use 'include' instead of 'ilude'):

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

    Remove the other includes that are present in this file. Save this file.

13. Open up my-first-module.adoc in the modules folder. At the top of this file, in the comments section, add the following to indicate in which assembly this module is being used:

    // Module included in the following assemblies:
    //
    // my_guide/assembly_my-first-assembly.adoc

14. Open up _topic_map.yml from the root folder and add these lines at the end of this file and then save.

    ---
    Name: OpenShift CCS Mod Docs First Guide
    Dir: my_guide
    Distros: openshift-*
    Topics:
    - Name: My First Assembly
      File: assembly_my-first-assembly

15. On the command line, run asciibinder from the root folder of openshift-docs. You don’t have to add or commit your changes for asciibinder to run.

16. After the asciibinder build completes, open up your browser and navigate to <YOUR-LOCAL-GIT-REPO-LOCATION>/openshift-docs/_preview/openshift-enterprise/my_first_mod_docs/my_guide/assembly_my-first-assembly.html

17. Confirm that your book my_guide has an assembly My First Assembly with the contents from your module My First Module.

Note	You can delete this branch now if you are done testing. This branch shouldn’t be submitted to the upstream openshift-docs repository.