Include file

You can include files from a Bitbucket repository in order to have an up-to-date version of it in a Confluence page. The macro will feature syntax highlighting for the included file and the possibility to export it in PDF or Word.

To include a file you can:

simply paste the URL
add the file macro and specify the file path
add the file macro and specify a pattern to search for a set of files

For files that are within private repositories, users will need to authenticate to view the files' content. More information in this section.

Include file by pasting the file’s URL

You can simply copy the URL of the Bitbucket file and paste it into the Confluence page.

In the following example we use the file URL of a .adoc file located in a local Bitbucket repository. We simply paste the URL in the Confluence page as shown in the video and the macro will automatically be applied to embed the file.

To edit the macro’s options listed in the next section, you can click on the edit button present on the macro when editing the page.

Include file by adding the file macro

You can also add the macro to set further options.

In order to do so, you can either:

type directly { Bitbucket file and ENTER to add and edit the macro, or
click in the editor toolbar on Insert > Other Macros and select the Bitbucket file macro (located in the category “External Content” of the macro library).

You will then be able to specify the following:

`Bitbucket connection`	Dropdown of connections registered in the macro configuration
`Bitbucket project`	Name of the project within the connection containing the targeted repository
`Bitbucket repository`	Name of the repository containing the file
`Git branch/tag`	Name of the branch containing the file version to be displayed
`File path`	Path to the file
`Show line number`	Display number of lines in the file (default setting is disabled)
`Hide file header`	Hide the file name (default setting is disabled)
`File encoding`	Character encoding standard to be applied (default is `UTF-8`)
`Theme for syntax highlighting`	Specifies the color scheme used for displaying your code block. The default theme is `Confluence`, which is typically black and colored text on a blank background.
`Render file as`	Language of the file for syntax highlighting purposes
`File range by regex match (optional)`	Display part of the file that is included between a regex (start) and another one (end). Either can be left blank.
`File range by line number (optional)`	Display part of the file that is included between a line number (start) and another line number (end). Either can be left blank.
`Collapsible`	Collapses the file content and gives the option to expand and collapse

Include file by Ant pattern

This macro allows to include a configurable number of matching files by an Ant glob pattern from a Bitbucket Data Center repository.

In order to add the macro, you can either:

type directly { Bitbucket files by Ant pattern and ENTER to add and edit the macro, or
click in the editor toolbar on Insert > Other Macros and select the Bitbucket files by Ant pattern macro (located in the category “External Content” of the macro library).

Select the Bitbucket files by Ant pattern macro

You will then be able to specify the following:

`Bitbucket connection`	Dropdown of connections registered in the macro configuration
`Bitbucket project`	Name of the project within the connection containing the targeted repository
`Bitbucket repository`	Name of the repository containing the file
`Git branch/tag`	Name of the branch containing the file version to be displayed
`Ant glob pattern`	Pattern to match to select specific files from the repository - see here for supported Ant glob pattern syntax
`Choose maximum number of matches to show`	Number of files that will be returned from the Ant glob pattern-based search
`File encoding`	Character encoding standard to be applied (default is `UTF-8`)
`Theme for syntax highlighting`	Specifies the color scheme used for displaying your code block. The default theme is `Confluence`, which is typically black and colored text on a blank background.
`Hide file header`	Hide the file name (default setting is disabled)
`Show line number`	Display number of lines in the file (default setting is disabled)

Configuration parameters are the project, repository, branch, an Ant glob pattern (see here for its syntax) and the number of matching files to include into the Confluence page.

Editing the macro with repository and search pattern information

Demo videos

Curious how we used Oma’s famous sauerkraut recipe stored in Bitbucket? 🍲🥬
In this Apptoberfest 2024 video, we blend tradition with tech by showing how Include Bitbucket for Confluence keeps documentation and recipes in perfect sync!

Watch to see how Bitbucket files—Markdown, PlantUML diagrams, AsciiDoc, and more—are instantly rendered in Confluence, making collaboration effortless. Say goodbye to outdated Confluence docs, and keep them in sync between Confluence and Bitbucket automatically 🥳

In this video, we introduce PlantUML, a powerful tool that simplifies how your team creates and manages technical diagrams with just text.

🔍 What you'll learn:

How to render a PlantUML diagram directly in Confluence using the Include Bitbucket for Confluence app.
Automatically pull and render diagrams from Bitbucket repositories into Confluence for easy collaboration and streamlined documentation.
Watch as we take a PlantUML file and transform it into a sequence diagram, turning complex workflows into clear, visual guides.

Experience the latest update to Include for Confluence with an enhanced dark theme. Now, your Bitbucket files sync are in a dark theme, creating a smoother, more eye-friendly workflow across all your tools. Perfect for developers working late hours, this new feature ensures consistency and focus.