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 the Synapse Python client 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 its 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
- 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 a project, see the Projects tutorial.
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=15-31}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:
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=33-38}Alternatively, you can create a Wiki page from an existing markdown file.
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=41-46}You'll notice the output looks 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:
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=48-54}You'll notice the output looks 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:
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=56-59}Check if the content is restored.
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=61-71}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:
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=73-75}Alternatively, you can retrieve a Wiki page by its title:
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=77-78}Verify that the retrieved Wiki page matches the original Wiki page
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=80-89}You can create a sub-Wiki page under an existing Wiki page.
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=91-96}You'll notice the output looks 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 Python string. Here is an example of creating a Wiki page from a multi-line Python string:
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=98-121}You can also create a Wiki page from an existing markdown file. Markdown files may be uploaded in either non-gzipped or gzipped format:
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=123-133}You can download the markdown content of a Wiki page back to a file.
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=135-143}Download the markdown file for a Wiki page that is created from plain text, the downloaded file will be named wiki_markdown_<wiki_page_title>.md
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=145-148}You'll notice the output looks 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. ```{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=150-153}You'll notice the output looks 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 utilize the static method WikiPage.reformat_attachment_file_name to reformat the file name.
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=155-169}You'll notice the output looks 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).
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=171-182}You'll notice the output looks 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:
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=184-187}You'll notice the output looks like:
``` {'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. Attachment file name can be in either non-gzipped or gzipped format.
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=189-195}You'll notice the output looks like:
``` 'https://data.prod.sagebase.org/...' ```Download an attachment file to your local machine and unzip it using WikiPage.unzip_gzipped_file function.
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=197-204}You can also retrieve preview URLs for attachments. When using get_attachment_preview, 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.
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=206-213}Download the preview version of an attachment:
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=215-223}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 allows you to retrieve the hierarchical structure of Wiki pages within an entity.
Retrieve the complete Wiki page hierarchy for a project:
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=224-226}You'll notice the output shows the Wiki hierarchy:
``` [WikiHeader(id='...', title='My Root Wiki Page', ...), WikiHeader(id='...', title='Sub Wiki Page 1', ...)] ```WikiHistorySnapshot provides access to the version history of Wiki pages, allowing you to see all previous versions and their metadata.
Retrieve the version history for a specific Wiki page:
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=228-230}You'll notice the output shows the history of versions:
``` [WikiHistorySnapshot(version='..', modified_on='...', modified_by='...'), ..., WikiHistorySnapshot(version='...',...)] ```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):
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=232-234}You'll notice the output looks like:
``` WikiOrderHint(owner_id='...', owner_object_type='ENTITY', id_list=[], etag='...') ```Set the order of Wiki pages by providing a list of Wiki page IDs in the desired order:
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=235-244}You'll notice the output shows the updated order:
``` WikiOrderHint(id_list=['...', '...', ...]) ```You can update the order hint at any time by retrieving it, modifying the id_list, and storing it again:
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=246-256}Delete a Wiki page by providing the owner ID and Wiki page ID:
{!docs/tutorials/python/tutorial_scripts/wiki.py!lines=258-265}Click to show me
```python {!docs/tutorials/python/tutorial_scripts/wiki.py!} ```- [WikiPage][synapseclient.models.WikiPage]
- [WikiHeader][synapseclient.models.WikiHeader]
- [WikiHistorySnapshot][synapseclient.models.WikiHistorySnapshot]
- [WikiOrderHint][synapseclient.models.WikiOrderHint]
- [Project][synapseclient.models.Project]
- [syn.login][synapseclient.Synapse.login]
- Related tutorial: Projects