hardis:doc:mkdocs-to-cf
Description
Command BehaviorGenerates MkDocs HTML pages and uploads them to Cloudflare as a static site, secured with Cloudflare Access.This command automates the deployment of your project's documentation (built with MkDocs) to Cloudflare Pages, making it accessible and secure. It handles the entire process from HTML generation to Cloudflare configuration.Key operations performed:- MkDocs HTML Generation: Builds the MkDocs project into static HTML pages. It can use a locally installed mkdocs-material or a mkdocs Docker image.- Cloudflare Pages Project Creation/Update: Creates a new Cloudflare Pages project if one doesn't exist for your documentation, or updates an existing one.- Cloudflare Access Policy Assignment: Assigns a policy to restrict access to the deployed application, ensuring only authorized users can view your documentation.- Cloudflare Access Application Setup: Configures a Cloudflare Access application for the deployed site, integrating it with your Zero Trust policies.- HTML Page Upload: Deploys the generated HTML pages to Cloudflare Pages.- Browser Opening (Non-CI): Opens the newly deployed website in your default browser if the command is not run in a CI/CD environment.Prerequisite: The documentation must have been previously generated using sf hardis:doc:project2markdown --with-history.Customization: You can override default styles by customizing your mkdocs.yml file.More information can be found in the Documentation section.Environment Variables for Cloudflare Configuration:| Variable | Description | Default || :---------------------------------------- | :----------------------------------------------------------------------- | :------------------------------------: || CLOUDFLARE_EMAIL | Cloudflare account email | Required || CLOUDFLARE_API_TOKEN | Cloudflare API token | Required || CLOUDFLARE_ACCOUNT_ID | Cloudflare account ID | Required || CLOUDFLARE_PROJECT_NAME | Project name, also used for the site URL | Built from Git branch name || CLOUDFLARE_DEFAULT_LOGIN_METHOD_TYPE | Cloudflare default login method type | onetimepin || CLOUDFLARE_DEFAULT_ACCESS_EMAIL_DOMAIN | Cloudflare default access email domain | @cloudity.com || CLOUDFLARE_EXTRA_ACCESS_POLICY_ID_LIST | Comma-separated list of additional policy IDs to assign to the application | Optional |
The command orchestrates interactions with MkDocs, Cloudflare APIs, and Git:- MkDocs Integration: It calls generateMkDocsHTML() to execute the MkDocs build process, which converts Markdown files into static HTML. It checks for the presence of mkdocs.yml to ensure it's a valid MkDocs project.- Cloudflare API Interaction: It uses the cloudflare npm package to interact with the Cloudflare API. This involves: - Authentication: Initializes the Cloudflare client using CLOUDFLARE_EMAIL, CLOUDFLARE_API_TOKEN, and CLOUDFLARE_ACCOUNT_ID environment variables. - Pages Project Management: Calls client.pages.projects.get() to check for an existing project and client.pages.projects.create() to create a new one if needed. - Access Policy Management: Lists existing access policies (client.zeroTrust.access.policies.list()) and creates a new one (client.zeroTrust.access.policies.create()) if the required policy doesn't exist. It configures the policy with email domain restrictions and a default login method. - Access Application Management: Lists existing access applications (client.zeroTrust.access.applications.list()) and creates a new one (client.zeroTrust.access.applications.create()) for the deployed site. It then updates the application to associate it with the created access policy.- Git Integration: Retrieves the current Git branch name using getCurrentGitBranch() to construct the Cloudflare project name and branch for deployment.- Wrangler CLI: Uses the wrangler CLI (Cloudflare's developer tool) to deploy the generated HTML pages to Cloudflare Pages via wrangler pages deploy.- Environment Variable Management: Reads various environment variables to configure Cloudflare settings and project names.- Error Handling: Includes checks for missing mkdocs.yml and Cloudflare environment variables, throwing SfError when necessary.
Parameters
| Name | Type | Description | Default | Required | Options |
|---|---|---|---|---|---|
| debug -d |
boolean | Activate debug mode (more logs) | |||
| flags-dir | option | undefined | |||
| json | boolean | Format output as json. | |||
| skipauth | boolean | Skip authentication check when a default username is required | |||
| websocket | option | Websocket host:port for VsCode SFDX Hardis UI integration |
Examples
$ sf hardis:doc:mkdocs-to-cf