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
- base.yml : configuration file for MkDocs
- mkdocs.yml : configuration file for MkDocs
- requirements.txt : MkDocs dependencies
- Dockerfile : configuration file for building container
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.
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
- 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"
- 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.
- Go to the Export / Import menu in Cognitive Architect
- Select Export and click Next
- Select GitHub Pages and provide your github repository link and token
- Click the Export button
- 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.
💡 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}/
orhttps://{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.
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.
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.
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.
There are two approaches to serve up the GitHub pages from a local machine.
Note that python 3.x
has to be installed on your machine in order to use this approach.
In a terminal window:
- Download your repository to your local machine
- see https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository for more information
- In the directory where your repository is, run
make venv
to create the python environment - Run
make serve
to serve up the GitHub pages on your local machine - Once the server is up, you can view the pages using the URL, for eg,
http://127.0.0.1:8000/{github_account}/{repo_name}/
Note that podman
has to be installed on your machine in order to use this approach.
In a terminal window:
- Download your repository to your local machine
- see https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository for more information
- In the directory where your repository is, run
make podman
to build the image - Run
make podman-run
to serve up the GitHub pages on your local machine - Once the server is up, you can view the pages using the URL, for eg,
http://127.0.0.1:8000/
Please refer to the OIC Handbook Template.
Your participation is greatly appreciated.