Overview
Wikis in Synapse provide rich documentation and collaborative content for projects, folders, files, datasets, and other entities. They support markdown formatting, file attachments, hierarchical organization, version history, and custom ordering. Wikis are managed through synapser using models like:
- WikiPage: The main Wiki page model for creating and managing Wiki content
- WikiHeader: Represents Wiki page headers and hierarchy information
- WikiHistorySnapshot: Provides access to Wiki version history
- WikiOrderHint: Manages the order of Wiki pages within an entity
Important: Wikis inherit the sharing permissions of their associated Synapse entities. Anyone with view access or higher can see the Wiki’s content. If a project, folder, or file is shared publicly, the linked Wiki will also be publicly visible, including to users who are not logged in to Synapse. For this reason, protected human data must not be stored in Synapse Wikis.
You can view your Wiki pages in the Synapse web UI by navigating to your project and clicking on the Wiki tab.
In this tutorial you will:
- Create, read, update, and restore Wiki pages
- Create Wiki pages from markdown text and files, and download markdown content
- Create Wiki pages with attachments, retrieve attachment handles and URLs, and download attachments and previews
- Retrieve Wiki page hierarchy using WikiHeader
- Access Wiki version history using WikiHistorySnapshot
- Get, set, and update Wiki page ordering using WikiOrderHint
- Delete Wiki pages
Prerequisites
- Make sure that you have completed the Installation and Authentication setup.
- This tutorial assumes you have a basic understanding of Synapse projects. If you need to create one, see the Project.
1. Create a Wiki page
Initial setup
library(synapser)
synLogin()
project <- Project(
name = paste0(
"My uniquely named project about Alzheimer's Disease ",
paste(sample(c(letters, LETTERS, 0:9), 8, replace = TRUE), collapse = "")
)
) |> synStore()
cat("Created project:", project$id, "\n")
project <- Project(name = "My uniquely named project about Alzheimer's Disease") |> synGet()A Wiki page requires an owner object, a title, and markdown. Here is an example to create a new root Wiki page for your project with plain text markdown:
root_wiki_page <- WikiPage(
owner_id = project$id,
title = "My Root Wiki Page",
markdown = "# Welcome to My Root Wiki\n\nThis is a sample root wiki page created with the Synapse client."
) |> synStore()Alternatively, you can create a Wiki page from an existing markdown file.
markdown_file_path <- "path/to/your_markdown_file.md"
root_wiki_page <- WikiPage(
owner_id = project$id,
title = "My First Root Wiki Page Version with existing markdown file",
markdown = markdown_file_path
) |> synStore()You’ll see output like:
Uploaded file handle ... for Wiki page markdown.
No Wiki page exists within the owner. Create a new Wiki page.
Created Wiki page: My Root Wiki Page with ID: ...
2. Update a Wiki page
To update an existing Wiki page, create a new WikiPage object with
the same id and new content:
root_wiki_page_new <- WikiPage(
owner_id = project$id,
title = "My First Root Wiki Page NEW",
markdown = "# Welcome to My Root Wiki NEW\n\nThis is a sample root wiki page created with the Synapse client.",
id = root_wiki_page$id
) |> synStore()You’ll see output like:
Uploaded file handle ... for Wiki page markdown.
A Wiki page already exists within the owner. Update the existing Wiki page.
Updated Wiki page: My First Root Wiki Page NEW with ID: ...
3. Restore a Wiki page to a previous version
You can restore a Wiki page to any previous version by specifying the
wiki_version parameter:
wiki_page_restored <- WikiPage(
owner_id = project$id, id = root_wiki_page$id, wiki_version = "0"
) |> synRestore()Check if the content is restored:
4. Get a Wiki page
You can retrieve Wiki pages in several ways. To find a Wiki page id, you can get the WikiHeader tree to see all Wiki pages in the hierarchy (see the WikiHeader section below).
Once you know the Wiki page id, you can retrieve a specific Wiki page:
Alternatively, you can retrieve a Wiki page by its title:
Verify that the retrieved Wiki page matches the original Wiki page:
5. Create a sub-Wiki page
You can create a sub-Wiki page under an existing Wiki page.
sub_wiki_1 <- WikiPage(
owner_id = project$id,
title = "Sub Wiki Page 1",
parent_id = root_wiki_page$id,
markdown = "# Sub Page 1\n\nThis is a sub-page of another wiki."
) |> synStore()You’ll see output like:
Uploaded file handle ... for wiki page markdown.
Creating sub-wiki page under parent ID: ...
Created sub-wiki page: Sub Wiki Page 1 with ID: ... under parent: ...
6. Create a Wiki page from markdown
Create a Wiki page directly from a string
You can create a Wiki page from a single-line or multi-line string. Here is an example of creating a Wiki page from multi-line markdown text:
markdown_content <- "# Sample Markdown Content
## Section 1
This is a sample markdown file with multiple sections.
## Section 2
- List item 1
- List item 2
- List item 3
## Section 3
- List item 1
- List item 2
- List item 3
"
sub_wiki_2 <- WikiPage(
owner_id = project$id,
parent_id = root_wiki_page$id,
title = "Sub Page 2 created from markdown text",
markdown = markdown_content
) |> synStore()7. Download Wiki page markdown
You can download the markdown content of a Wiki page back to a file.
Download the markdown file URL for a Wiki page
wiki_page_markdown_2_url <- WikiPage(
owner_id = project$id,
id = sub_wiki_2$id
) |> synGetMarkdownFile(download_file = FALSE)Download the markdown file for a Wiki page created from plain text
The downloaded file will be named
wiki_markdown_<wiki_page_title>.md:
wiki_page_markdown_2 <- WikiPage(
owner_id = project$id, id = sub_wiki_2$id
) |> synGetMarkdownFile(download_file = TRUE, download_location = ".")You’ll see output like:
Your markdown content in plain text
Downloaded and unzipped the markdown file for wiki page ... to path/to/wiki_markdown_Sub Page 2 created from markdown text.md.
Download the markdown file for a Wiki page created from a markdown file
wiki_page_markdown_3 <- WikiPage(
owner_id = project$id, id = sub_wiki_3$id
) |> synGetMarkdownFile(download_file = TRUE, download_location = ".")You’ll see output like:
Downloaded and unzipped the markdown file for wiki page ... to path/to/sample_wiki.md.
8. Create Wiki pages with attachments
Wiki pages can include file attachments, which are useful for sharing supplementary materials such as images, data files, or documents. Attachment files may be uploaded in either non-gzipped or gzipped format.
Create a Wiki page with attachments
First, create a file to attach. Then create a Wiki page with the
attachment. Note that attachment file names in markdown need special
formatting: replace . with %2E and
_ with %5F. You can use
synReformatAttachmentFileName() to reformat the file
name.
attachment_file_name <- "path/to/temp_attachment.txt"
# Reformat "." and "_" in the attachment file name to be a valid attachment path
attachment_file_name_reformatted <- synReformatAttachmentFileName(basename(attachment_file_name))
sub_wiki_4 <- WikiPage(
owner_id = project$id,
parent_id = root_wiki_page$id,
title = "Sub Page 4 with Attachments",
markdown = sprintf("# Sub Page 4 with Attachments\n\nThis is a attachment: ${previewattachment?fileName=%s}", attachment_file_name_reformatted),
attachments = list(attachment_file_name)
) |> synStore()You’ll see output like:
Uploaded file handle ... for wiki page attachment.
Creating sub-wiki page under parent ID: ...
Created sub-wiki page: Sub Page 4 with Attachments with ID: ... under parent: ...
To include images in your Wiki page, you do NOT need to reformat the file name for image files (e.g., PNG, JPG, JPEG).
image_file_path <- "path/to/test_image.png"
markdown_content <- "# Sub Page 5 with images\n\nThis is an attached image: ${image?fileName=test_image.png&align=None&scale=100&responsive=true&altText=}"
sub_wiki_5 <- WikiPage(
owner_id = project$id,
parent_id = root_wiki_page$id,
title = "Sub Page 5 with Images",
markdown = markdown_content,
attachments = list(image_file_path)
) |> synStore()You’ll see output like:
Uploaded file handle ... for wiki page attachment.
Creating sub-wiki page under parent ID: ...
Created sub-wiki page: Sub Page 5 with Attachments with ID: ... under parent: ...
9. Retrieve attachment handles and URLs, and download attachments and previews
Get attachment handles
Retrieve the file handles of all attachments on a Wiki page:
attachment_handles <- WikiPage(
owner_id = project$id, id = sub_wiki_4$id
) |> synGetAttachmentHandles()You’ll see output like:
list(list(id = "...", etag = "...", concreteType = "org.sagebionetworks.repo.model.file.S3FileHandle", contentType = "...", contentMd5 = "...", fileName = "...", storageLocationId = 1, ..., isPreview = FALSE))
Get attachment URL without downloading
You can retrieve the URL of an attachment without downloading it. The attachment file name can be in either non-gzipped or gzipped format.
wiki_page_attachment_url <- WikiPage(
owner_id = project$id, id = sub_wiki_4$id
) |> synGetAttachment(
file_name = basename(attachment_file_name),
download_file = FALSE
)You’ll see output like:
"https://data.prod.sagebase.org/..."
Download an attachment file
Download an attachment file to your local machine and unzip it using
synUnzipGzippedFile():
Get attachment preview URL
You can also retrieve preview URLs for attachments. When using
synGetAttachmentPreview(), specify the original file name,
not the file name returned in the attachment handle response when
isPreview=TRUE. The file name can be in either non-gzipped
or gzipped format. The downloaded file will still be named according to
the file name provided in the response when isPreview=TRUE.
Note that image attachments do not have preview files.
Download an attachment preview
Download the preview version of an attachment:
attachment_preview <- WikiPage(
owner_id = project$id, id = sub_wiki_4$id
) |> synGetAttachmentPreview(
file_name = basename(attachment_file_name),
download_file = TRUE,
download_location = "."
)The downloaded preview file will be named
preview.<your attachment file type> (or according to
the file name in the attachment handle response when
isPreview=TRUE).
10. Retrieve Wiki page hierarchy using WikiHeader
WikiHeader represents the hierarchical structure of Wiki pages within an entity.
Retrieve the Wiki page hierarchy of an entity by piping an empty
WikiHeader() into synGet() with the entity’s
owner_id. The result is a lazy iterator, so call
as.list() on it to get a list of WikiHeader
objects, each with an id, title, and
parent_id:
wiki_headers <- as.list(WikiHeader() |> synGet(owner_id = project$id))
for (header in wiki_headers) {
print(header)
}11. Access Wiki version history using WikiHistorySnapshot
WikiHistorySnapshot provides access to the version history of Wiki pages, letting you see all previous versions and their metadata.
Retrieve the version history of a Wiki page by piping an empty
WikiHistorySnapshot() into synGet() with the
owner_id and the Wiki page id. As with
WikiHeader, call as.list() on the result to
get a list of WikiHistorySnapshot objects, each with a
version, modified_on, and
modified_by:
wiki_history <- as.list(
WikiHistorySnapshot() |> synGet(owner_id = project$id, id = root_wiki_page$id)
)
for (snapshot in wiki_history) {
print(snapshot)
}12. Get, set, and update Wiki page ordering using WikiOrderHint
WikiOrderHint allows you to control the order in which Wiki pages are displayed. By default, Wiki pages don’t have an explicit order, so you need to set it explicitly.
Get the current order hint
First, retrieve the current order hint (which may be empty initially):
order_hint <- WikiOrderHint(owner_id = project$id) |> synGet()You’ll see output like:
WikiOrderHint(owner_id = "...", owner_object_type = "ENTITY", id_list = list(), etag = "...")
Set the Wiki order hint
Set the order of Wiki pages by providing a list of Wiki page IDs in the desired order:
order_hint <- order_hint |>
synSetProperties(
id_list = list(
root_wiki_page$id,
sub_wiki_3$id,
sub_wiki_4$id,
sub_wiki_1$id,
sub_wiki_2$id,
sub_wiki_5$id
)
) |>
synStore()You’ll see output like:
WikiOrderHint(id_list = list("...", "...", ...))
Update Wiki order hint
You can update the order hint at any time by retrieving it, modifying
the id_list, and storing it again:
order_hint <- WikiOrderHint(owner_id = project$id) |> synGet()
order_hint <- order_hint |>
synSetProperties(
id_list = list(
root_wiki_page$id,
sub_wiki_1$id,
sub_wiki_2$id,
sub_wiki_3$id,
sub_wiki_4$id,
sub_wiki_5$id
)
) |>
synStore()Where to go next
- The WikiPage reference page
documents every constructor argument and method available on a WikiPage,
including
synGetAttachment(),synGetAttachmentPreview(),synGetMarkdownFile(),synRestore(),synReformatAttachmentFileName(), andsynUnzipGzippedFile(). - WikiHeader, WikiHistorySnapshot, and WikiOrderHint document the supporting Wiki metadata models.
- Data Upload, Download, and Delete covers the Project/Folder/File workflow this tutorial builds on.