ITAA_Markdown

Introduction

This is the markdown repository template for the "Export to GitHub Pages" utility in Cognitive Architect (aka IBM IT Architect Assistant - SaaS Version). With Release 3.16.5, the template is now based on the OIC Handbook Template.

The export utility creates markdown files containing the architecture information and then generates the corresponding GitHub Pages of the architecture using MkDocs, ejs, MkDocs Awesome Pages plugin and Material for MkDocs.

It consists of the following folders:

• docs
• includes
• templates
  • official_template : contains the architectural artifacts' default ejs templates
  • user_template : user-defined templates that overrides the default ones
• theme : contains the theme used for the generated pages

and files:

• Makefile : for redeploying changes made to the theme and/or markdown files
• README.md : this page
• mkdocs.yml : configuration file for MkDocs
• requirements.txt : MkDocs dependencies

When the export is successfully executed:

• the markdown files containing the various architectural artifacts and instances will be stored in the docs folder AND
• a json file containing all the architecture information (archData_[architecture-name].json) will also be created

If there are concerns about who can view/access the generated GitHub Pages, read the Access Considerations section before proceeding.

---

Setup

Before executing the export utility, you will need the following:

• a GitHub repository to contain the generated markdown docs and GitHub pages
• a GitHub token for access

1. Create a GitHub repository based on a markdown repository template

For IBM Enterprise GitHub setup

• go to the GHE markdown repository template
• click on "Use this template" to create a new repository based on the template
• provide a name for your repository, for eg the architecture name that you are exporting from
• click on "Create repository from template"

For Public GitHub setup

• go to the Public GitHub markdown repository template
• click on "Use this template" to create a new repository based on the template
• provide a name for your repository, for eg the architecture name that you are exporting from
• click on "Create repository from template"

If you are using GitHub Free, your repository has to be set as public. More information on GitHub Pages configuration here.

2. Generate the GitHub token with repo access. This is needed so that the export utility can generate the appropriate files into your GitHub repo.

For help on creating the token and getting the repository URL, go to GitHub Repo URL & Token.

💡 Tip: At a minimum, each architecture should have its own git repository! If you want to show different content based on your target audience or purpose, export them to different GitHub repositories.

---

Usage in Cognitive Architect : Export - GitHub Pages Utility

1. Go to the Export / Import menu in Cognitive Architect
2. Select Export and click Next
3. Select GitHub Pages and provide your github repository link and token
4. Click the Export button
5. The Export utility will execute in the background and you will be notified and provided with the link to the published pages when the export is done.

⚠️ Warning: Do not close the browser window after the Export request has been submitted! The URL of your GitHub Pages will be returned when the export is completed.

💡 Tip: You can continue to work in Cognitive Architect while your Export request is being processed.

If you did not see or get the URL, your GitHub Pages can typically be accessed via:

• https://pages.{enterprise_github_domain}/{github_account}/{repo_name}/or
• https://{github_account}.github.io/{repo_name}/

If you get a "404 - Page/File Not Found" error, check your repository's Settings -> GitHub Pages for the correct URL.

---

GitHub Repo Token & URL

To generate an access token for your repository:

• Navigate to [repository-url]/settings/tokens/new (e.g. https://github.ibm.com/settings/tokens/new)
• Add a description, for e.g. iiaa-access and select repo scope
• Click the "Generate Token" button
• Click on the clipboard icon (📋) to copy the token and save it somewhere. You will need this in the "Export dialog" in IBM IT Architect Assistant. Note that you cannot retrieve the token from Git after you leave the Token generation page.

For this export function, you have to use the HTTPS repository URL, regardless of whether your target repository is in Enterprise Git or Public Git.

Sample HTTPS URLs are:

• https://github.ibm.com/owner-name/IIAA_Markdown_arch1.git (GHE)
• https://github.com/owner-name/IIAA_Markdown_arch5.git (Public)

You can retrieve the URL by clicking on the Code button for your repository and copy the HTTPS URL.

---

Access Considerations

GitHub Pages is designed to host your personal, organization, or project pages from a GitHub repository. In the GitHub Pages Docs, the following is called out:

GitHub Pages is available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server.

It is important to understand who can view the Pages.

• In Public GitHub, since the repository has to be public, anyone can see the generated GitHub Pages
• In Enterprise GitHub, the repository can be private, BUT the published site will be visible to all enterprise members.

To limit access to your GitHub Pages, one option is to serve up the pages from a local machine.

• Execute steps 1 through 3 outlined in the Refreshing your Pages section
• When the make serve command is completed, you can view the pages using the URL generated, for eg, http://127.0.0.1:8000/{github_account}/{repo_name}/

---

Customization

The export utility uses MkDocs with the ejs template engine to generate the markdown files. The Material for MkDocs theme for MkDocs is then used to generate the GitHub Pages.

We chose ejs as our template engine because of its performance and ease of understanding since it is closer to pure HTML.

To customize the markdown files:

• Copy the ejs file(s) to be changed from the templates/official_template folder to the templates/user_template one. Note: Do not change the name of the file(s).
• Modify the content as needed.
• Re-submit the Export request in IBM IT Architect Assistant.

To change the look & feel of your pages:

• refer to Material for MkDocs - Customization](https://squidfunk.github.io/mkdocs-material/customization/) on how to customize the themes
• Re-submit the Export request in IBM IT Architect Assistant.

💡 Tip: If the GitHub Pages do not reflect your latest updates, clear the cache and refresh.

---

Feedback and Contributions

Please refer to the OIC Handbook Template.

Your participation is greatly appreciated.