Working with a README file

Upload a README.md file containing instructions, diagrams, and essential information for your workflow. Each workflow version supports one README file, which can be updated anytime.

README requirements include:

• README file must be in markdown (.md) format

• Maximum file size: 500 KiB

Use an existing README

READMEs exported from Git repositories contain relative links that typically do not work outside the repository. HealthOmics Git integration automatically converts these to absolute links for proper rendering in the console, eliminating the need for manual URL updates.

For READMEs imported from Amazon S3 or local drives, images and links must either use public URLs or have their relative paths updated for proper rendering.

Note

Images must be publicly hosted to display in the HealthOmics console. Images stored in GitHub Enterprise Server or GitLab Self-Managed repositories cannot be rendered.

Rendering conditions

The HealthOmics console interpolates publicly accessible images and links using absolute paths. To render URLs from private repositories, the user must have access to the repository. For GitHub Enterprise Server or GitLab Self-Managed repositories, which use custom domains, HealthOmics cannot resolve relative links or render images stored in these private repositories.

The following table shows the markdown elements that are supported by the AWS console README view.

Element	AWS console
Alerts	Yes, but without icons
Badges	Yes
Basic text formatting	Yes
Code blocks	Yes, but does not have syntax highlight and copy button functionality
Collapsible sections	Yes
Headings	Yes
Image formats	Yes
Image (clickable)	Yes
Line breaks	Yes
Mermaid diagram	Only can open graph, move graph position, and copy code
Quotes	Yes
Subscript and superscript	Yes
Tables	Yes, but does not support text alignment
Text alignment	Yes

Using image and link URLs

Depending on your source provider, structure your base URLs for pages and images in the following formats.

• {username}: The username where the repository is hosted.

• {repo}: The repository name.

• {ref}: The source reference (branch, tag, and commit ID).

• {path}: The file path to the page or image in the repository.

Source provider	Page URL	Image URL
GitHub	https://github.com/{username}/{repo}/blob/{ref}/{path}	https://github.com/{username}/{repo}/blob/{ref}/{path}?raw=true https://raw.githubusercontent.com/{username}/{repo}/{ref}/{path}
GitLab	https://gitlab.com/{username}/{repo}/-/blob/{ref}/{path}	https://gitlab.com/{username}/{repo}/-/raw/{ref}/{path}
Bitbucket	https://bitbucket.org/{username}/{repo}/src/{ref}/{path}	https://bitbucket.org/{username}/{repo}/raw/{ref}/{path}

GitHub, GitLab, and Bitbucket support both page and image URLs that link to a public repository. The following table shows each source provider’s support for rendering image and link URLs for private repositories.

Private repository support
Source provider	Page URL	Image URL
GitHub	Only with access to repository	No
GitLab	Only with access to repository	No
Bitbucket	Only with access to repository	No