Cloudmarque Docs is a static HTML website built using Jekyll, the same technology which powers GitHub Pages. docs.trustmarque.com is hosted in Microsoft Azure, using the Cloudmarque PaaS component for static websites.
About content deployment
Our publishing pipeline can be started by changes in any one of three areas:
GitHub: Cloudmarque Docs
The contents of the Cloudmarque Docs Git repository are packaged raw into an Azure Pipelines artifact and published for consuption by other pipelines (see azure-pipelines.yml in the repository root for more information).
GitHub: Cloudmarque PowerShell Tools for Azure
The Cloudmarque PowerShell Tools for Azure build pipeline generates documentation which is are packaged (as raw Markdown files) into an Azure Pipelines artifact .and published for use by other pipelines.
Azure DevOps (TMS Docs Internal)
Our wider Documentation site content (including our blog, services, and additional help information) triggers the publishing pipeline when new changes are committed to the repository, or when a build is manually triggered.
The contents of this repository include Trustmarque branding and web assets in the form a Jekyll site.
The publishing pipeline:
- Begins by unpacking our Docs Jekyll site
- Imports the latest published documentation from Cloudmarque Powershell Tools for Azure
- Imports the latest published documentation for Cloudmarque
- Runs Jekyll build to turn raw assets into a static HTML website
- Performs validation tests
- Publishes the Jekyll site for consumption by further pipelines
Our infrastructure pipeline is triggered by availability of a new published Jekyll site, and:
- Deploys infrastructure (a Paas Web Static site)
- Deploys the site content into the infrastructure
Where to edit
To edit some content, first fork the documentation repository to your own account. Clone the repository:
git clone https://github.com/[ACCOUNT]/cloudmarque-docs.git
Next, create a new branch to hold your edits. Give this a clear name which describes the types of edit you want to make.
If you intend to make a number of independent edits then consider creating separate branches for each set of related changes. These can then be reviewed and potentially merged in smaller chunks.
git checkout -b [BRANCHNAME]
Add the main Cloudmarque repository as an upstream source. This will allow you to pull and merge any changes that are made to content while you make your edits.
git remote add upstream https://github.com/Trustmarque/cloudmarque-docs.git
Markdown pages can include HTML markup, in contiguous line blocks.
When you are happy with your changes, commit them with a descriptive message:
git commit -S -m "New wordage is of bester"
Push your changes to your forked repository:
git push -u origin [BRANCHNAME]
When you navigate to the branch on GitHub you will now see a new option to Create pull request. Fill in a title and then explain the changes that you’ve made, and why you’ve made them. For each pull request (PR) please include:
- Your motivation for making changes.
- A paragraph stating how widespread the changes are.
- Whether imagery/diagrams need to be updated, and whether these are included in the PR.
- Links or references evidencing that any guidance or advice is best practise (or otherwise).
- A picture of a cute animal is not mandatory, but encouraged.
We’ll then review the changes and use the Pull Request thread to communicate whether we’re in a position to merge the contribution.
Contributor Licence Agreement
Before your contribution is merged to Cloudmarque we ask that you complete a Contributor Licence Agreement. This allows you to retain copyright of the contributed material while promising not to exercise typical powers that copyright implies, enabling the community to be confident that their use of Cloudmarque is free from legal encumberances.
Once merged, your contribution will be automatically built and published to the Cloudmarque documentation on docs.trustmarque.com.
Edit this page on GitHub
The content on this page is published under Open Source licenses via GitHub. To submit issues or provide feedback please visit the repository.Visit