Include from GitHub to Confluence Cloud
Include from GitHub to Confluence Cloud
Breadcrumbs

FAQ


Is it possible to export Git assets to PDF or Word?

Yes, you can export Git assets (including files and other content) as part of a PDF or Word export of your Confluence page.


Why do I get a message asking me to authenticate to view content from a public repository?

GitHub applies a limit rate to unauthenticated requests made to retrieve content. It is possible that such rate limit may be reached prompting you to authenticate even to access public repositories. Once authenticated the user should be able to see the requested data.

Why does the app need “write” permission for the OAuth scope when allowing the Confluence instance for Github?

The app technically does not require “write“ permissions but unfortunately the GitHub API does not provide a read-only OAuth scope for public and/or private repos which is what our app needs and we are forced to use the “repo“ scope. Including GitHub documentation on Scopes for OAuth Apps as reference.

Advanced links such as {asciidoc-dir}/../../shared/versions/stack/{source_branch}.adoc are currently not supported and we display in the included file.

Why are images within a Markdown or AsciiDoc not rendered?

If images in your Markdown or AsciiDoc files aren’t rendering, it’s often due to the use of relative paths that can’t be resolved in the current context.

To ensure images are rendered correctly:

  • Use absolute paths relative to the repository root when possible.

  • Make sure the image file exists and is accessible at the specified path.

AsciiDoc

=== Picture 1 Block

image::/images/Example.png[]

=== Picture 2 Inline

image:/images/Example.png[]

Markdown 

![Alt text](/src/images/image.png)

How can I resize images in my files so they don’t take the full width and height?

You can add custom sizes to images in Markdown using HTML. While Markdown is great for formatted text, it doesn't natively support resizing images. But with the img tag, you can easily control image dimensions.

For example:

<img src="image.jpg" width="400" height="400"/>

Can I customize the file layout when exporting via PDF (e.g. image size)?

Yes, you can customize the layout for PDF exports, including the image size, by modifying the Confluence PDF stylesheet. For example, adding the following CSS rule to the PDF stylesheet will ensure that the images in the exported file are displayed at the same size:

.image-container img {
  width: 200px; 
  height: auto; 
}

For more details on customizing PDF exports, you can refer to the official Atlassian documentation: Customize Exports to PDF.

Branches with Slashes

Branches with slashes in their name (eg bugfix/issue-123, feature/abc) are not supported at the moment.

As a work around, replace the slash of the branch name in the URL with %2F, for example the bugfix/issue-123 branch URL https://github.com/your-org/yor-repo/blob/bugfix/issue-123/markdown/test-basic.md to https://github.com/your-org/yor-repo/blob/bugfix%2Fissue-123/markdown/test-basic.md

Let us know your use case here if you require support for slashes in branch names.

How can I include the C4-PlantUML library in my .puml files so the app renders them?

You can use !include <C4/C4_Container> for including the C4-PlantUML library.

Example:

@startuml
!include <C4/C4_Container>
Person(personAlias, "Label", "Optional Description")
Container(containerAlias, "Label", "Technology", "Optional Description")
System(systemAlias, "Label", "Optional Description")
System_Ext(extSystemAlias, "Label", "Optional Description")
Rel(personAlias, containerAlias, "Label", "Optional Technology")
Rel_U(systemAlias, extSystemAlias, "Label", "Optional Technology")
@enduml

Reference: https://plantuml.com/stdlib#062f75176513a666

How can I include the PlantUML Standard library?

To use the official Standard Library for PlantUML, you can use the following syntax in the PlantUML file:

!include <awslib/AWSCommon>
!include <awslib/Groups/all>
!include <awslib/ApplicationIntegration/MQ>
!include <awslib/Database/DocumentDB>
!include <awslib/Database/RDS>
!include <awslib/Containers/Containers>
!include <awslib/Storage/SimpleStorageService>
!include <awslib/Storage/SimpleStorageServiceGlacier>
!include <awslib/ApplicationIntegration/APIGateway>
!include <awslib/SecurityIdentityCompliance/Cognito>
!include <awslib/Database/DocumentDB>
!include <awslib/Database/RDS>
!include <awslib/Compute/Lambda>
!include <awslib/InternetOfThings/IoTThingGeneric>

Why do my nested AsciiDoc includes fail in Confluence?

Nested include:: directives can fail to render in Confluence when paths cannot be resolved or unsupported AsciiDoc features are used.

Common causes

  • Unsupported path variables used inside include:: directives

Supported behavior

To ensure included files are rendered correctly:

  • Use relative or repository-root absolute paths for all include:: directives.

    include::docs/architecture/overview.adoc[]

  • Verify the file exists and is accessible at the specified path in the repository.

What dialect of Markdown is supported?

Our app supports CommonMark, the formal specification for modern Markdown.
In addition to CommonMark’s core features, we enable a focused set of extensions that provide functionality users commonly expect. Some of these extensions overlap with capabilities found in GitHub-Flavored Markdown (GFM), but we do not implement the full GFM specification.

Below is the complete list of supported extensions, each with a short example demonstrating how it works.

1. Tables (TableExtension)

Supports pipe-style tables and column alignment.

Example:

| Name  | Role      | Location |
|-------|-----------|----------|
| Alice | Developer | Zurich   |
| Bob   | Designer  | London   |

Automatically turns URLs and email addresses into links.

Example: 

https://example.com
user@example.com

3. Heading Anchor IDs (HeadingAnchorExtension)

Automatically generates stable id attributes for headings.
This allows users to link to specific sections within a document.

Example:

# Overview 

See the Scope section below:
[Go to Scope](#scope)
---
## Scope
This is the Scope section content.

4. Strikethrough (StrikethroughExtension)

Adds support for strikethrough syntax~~text~~ .

Example:

This text has ~~strikethrough~~ formatting.

Why does certain raw HTML in Markdown break when there are blank lines?

This behavior is expected and is caused by our use of the CommonMark specification. 

According to the CommonMark specification (Section 4.6 – HTML blocks), certain raw HTML blocks are terminated by a blank line. When a blank line appears inside one of these blocks, CommonMark treats it as the end of the block.

As a result, inserting blank lines between HTML elements can cause the parser to split the HTML into multiple blocks. Child elements may then be rendered outside of their intended parent element, producing unexpected or invalid HTML output.

This behavior is commonly encountered with elements such as <details>, <div>, and <table>, but can apply to other block-level HTML elements as well.

Recommendation

When using raw HTML in Markdown, do not include blank lines inside HTML blocks.

Ensure that all child elements appear directly after the opening tag and before the closing tag, without empty lines between them.

Example:

<details>
<summary>Expand</summary>
<ul>
  <li>Item A</li>
</ul>
</details>