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:
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:
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: ...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: ...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:
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:
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: ...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()You can also create a Wiki page from an existing markdown file. Markdown files may be uploaded in either non-gzipped or gzipped format:
You can download the markdown content of a Wiki page back to a file.
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.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.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.
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: ...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))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 to your local machine and unzip it using
synUnzipGzippedFile():
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 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).
WikiHeader represents the hierarchical structure of Wiki pages within an entity.
Note: In the Python client,
WikiHeader.get() retrieves this hierarchy as a paginated
list of WikiHeader objects for a given
owner_id. This is a classmethod with a signature
(owner_id, offset, limit) that
doesn’t match synapser’s generic synGet() factory function,
and there is currently no dedicated synGetXxx() wrapper for
it in synapser — I could not verify that this retrieval is exposed in R
yet, so no code sample is shown here. Check the WikiHeader reference page for
the current state of this before relying on it.
WikiHistorySnapshot provides access to the version history of Wiki pages, letting you see all previous versions and their metadata.
Note: The same gap applies here as with WikiHeader
above: WikiHistorySnapshot.get() in the Python client is a
classmethod (owner_id, id,
offset, limit) that doesn’t match
synGet()’s signature, and no dedicated R wrapper page
exists for it. I could not verify this is exposed in R yet — check the
WikiHistorySnapshot
reference page before relying on it.
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.
First, retrieve the current order hint (which may be empty initially):
You’ll see output like:
WikiOrderHint(owner_id = "...", owner_object_type = "ENTITY", id_list = list(), etag = "...")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("...", "...", ...))You can update the order hint at any time by retrieving it, modifying
the id_list, and storing it again:
Delete a Wiki page by providing the owner ID and Wiki page ID:
synGetAttachment(),
synGetAttachmentPreview(),
synGetMarkdownFile(), synRestore(),
synReformatAttachmentFileName(), and
synUnzipGzippedFile().