Wikis¶

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.

Tutorial Purpose¶

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 a project, see the Projects tutorial.

1. Create a Wiki page¶

Initial setup¶

import os

from synapseclient import Synapse
from synapseclient.models import (
    Project,
    WikiHeader,
    WikiHistorySnapshot,
    WikiOrderHint,
    WikiPage,
)

syn = Synapse()
syn.login()

# Get the project
project = Project(name="My uniquely named project about Alzheimer's Disease").get()

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:

# Create a new wiki page for the 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.",
).store()

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,
).store()

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: ...

2. Update a Wiki page¶

To update an existing Wiki page, create a new WikiPage object with the same id and new content:

# Update the wiki page
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,
).store()

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: ...

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:

# Restore the wiki page to the original version
wiki_page_restored = WikiPage(
    owner_id=project.id, id=root_wiki_page.id, wiki_version="0"
).restore()

Check if the content is restored.

# check if the content is restored
assert (
    root_wiki_page.markdown_file_handle_id == wiki_page_restored.markdown_file_handle_id
), "Markdown file handle ID does not match after restore"
assert (
    root_wiki_page.id == wiki_page_restored.id
), "Wiki page ID does not match after restore"
assert (
    root_wiki_page.title == wiki_page_restored.title
), "Wiki page title does not match after restore"

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:

# Once you know the Wiki page id, you can retrieve the Wiki page with the id
retrieved_wiki = WikiPage(owner_id=project.id, id=root_wiki_page.id).get()

Alternatively, you can retrieve a Wiki page by its title:

retrieved_wiki = WikiPage(owner_id=project.id, title=root_wiki_page.title).get()

Verify that the retrieved Wiki page matches the original Wiki page

assert (
    root_wiki_page.markdown_file_handle_id == retrieved_wiki.markdown_file_handle_id
), "Markdown file handle ID does not match retrieved wiki page"
assert (
    root_wiki_page.id == retrieved_wiki.id
), "Wiki page ID does not match retrieved wiki page"
assert (
    root_wiki_page.title == retrieved_wiki.title
), "Wiki page title does not match retrieved 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.",
).store()

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: ...

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 Python string. Here is an example of creating a Wiki page from a multi-line Python string:

# Section 2: WikiPage Markdown Operations
# Create wiki page from 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,
).store()

Create a Wiki page from a markdown file¶

You can also create a Wiki page from an existing markdown file. Markdown files may be uploaded in either non-gzipped or gzipped format:

# Create a wiki page from a markdown file
markdown_file_path = "~/temp/temp_markdown_file.md.gz"

# Create wiki page from markdown file
sub_wiki_3 = WikiPage(
    owner_id=project.id,
    parent_id=root_wiki_page.id,
    title="Sub Page 3 created from markdown file",
    markdown=markdown_file_path,
).store()

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¶

# Download the markdown file
# Note: If the markdown is generated from plain text using the client, the downloaded file will be named wiki_markdown_<wiki_page_title>.md.gz. If it is generated from an existing markdown file, the downloaded file will retain the original filename.
# Download the markdown file for sub_wiki_2 that is created from markdown text
wiki_page_markdown_2_url = WikiPage(
    owner_id=project.id,
    id=sub_wiki_2.id,
).get_markdown_file(
    download_file=False,
)

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`¶

# Download the markdown file for sub_wiki_2 that is created from markdown text
wiki_page_markdown_2 = WikiPage(
    owner_id=project.id, id=sub_wiki_2.id
).get_markdown_file(download_file=True, download_location=".")

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.

Download the markdown file for a Wiki page that is created from a markdown file¶

# Download the markdown file for sub_wiki_3 that is created from a markdown file
wiki_page_markdown_3 = WikiPage(
    owner_id=project.id, id=sub_wiki_3.id
).get_markdown_file(download_file=True, download_location=".")

You'll notice the output looks 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 utilize the static method WikiPage.reformat_attachment_file_name to reformat the file name.

# Section 3: WikiPage with Attachments
# Create a temporary file for the attachment
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 = WikiPage.reformat_attachment_file_name(
    os.path.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=f"# Sub Page 4 with Attachments\n\nThis is a attachment: ${{previewattachment?fileName={attachment_file_name_reformatted}}}",
    attachments=[attachment_file_name],
).store()

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).

# Inlucde images in the markdown file
image_file_path = "path/to/test_image.png"
# use the original file name instead of the gzipped file name for images
image_file_name = os.path.basename(image_file_path)
markdown_content = f"# 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=[image_file_path],
).store()

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: ...

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:

# Get attachment handles
attachment_handles = WikiPage(
    owner_id=project.id, id=sub_wiki_4.id
).get_attachment_handles()

You'll notice the output looks like:

{'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. Attachment file name can be in either non-gzipped or gzipped format.

# Get attachment URL without downloading
wiki_page_attachment_url = WikiPage(
    owner_id=project.id, id=sub_wiki_4.id
).get_attachment(
    file_name=os.path.basename(attachment_file_name),
    download_file=False,
)

You'll notice the output looks like:

'https://data.prod.sagebase.org/...'

Download an attachment file¶

Download an attachment file to your local machine and unzip it using WikiPage.unzip_gzipped_file function.

# Download an attachment
wiki_page_attachment = WikiPage(owner_id=project.id, id=sub_wiki_4.id).get_attachment(
    file_name=os.path.basename(attachment_file_name),
    download_file=True,
    download_location=".",
)
# Unzip the attachment file
unzipped_attachment_file_path = WikiPage.unzip_gzipped_file(wiki_page_attachment)

Get attachment preview URL¶

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.

# Download an attachment preview. Instead of using the file_name from the attachmenthandle response when isPreview=True, you should use the original file name in the get_attachment_preview request. The downloaded file will still be named according to the file_name provided in the response when isPreview=True.
# Get attachment preview URL without downloading
attachment_preview_url = WikiPage(
    owner_id=project.id, id=sub_wiki_4.id
).get_attachment_preview(
    file_name=os.path.basename(attachment_file_name),
    download_file=False,
)

Download an attachment preview¶

Download the preview version of an attachment:

# Download an attachment preview
attachment_preview = WikiPage(
    owner_id=project.id, id=sub_wiki_4.id
).get_attachment_preview(
    file_name=os.path.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 allows you to retrieve the hierarchical structure of Wiki pages within an entity.

Get Wiki header tree¶

Retrieve the complete Wiki page hierarchy for a project:

# Section 4: WikiHeader - Working with Wiki Hierarchy
# Get wiki header tree (hierarchy)
headers = WikiHeader.get(owner_id=project.id)

You'll notice the output shows the Wiki hierarchy:

[WikiHeader(id='...', title='My Root Wiki Page', ...), WikiHeader(id='...', title='Sub Wiki Page 1', ...)]

11. Access Wiki version history using WikiHistorySnapshot¶

WikiHistorySnapshot provides access to the version history of Wiki pages, allowing you to see all previous versions and their metadata.

Get Wiki history¶

Retrieve the version history for a specific Wiki page:

# Section 5. WikiHistorySnapshot - Version History
# Get wiki history for root_wiki_page
history = WikiHistorySnapshot.get(owner_id=project.id, id=root_wiki_page.id)

You'll notice the output shows the history of versions:

[WikiHistorySnapshot(version='..', modified_on='...', modified_by='...'), ..., WikiHistorySnapshot(version='...',...)]

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):

# Section 6. WikiOrderHint - Ordering Wiki Pages
# Set the wiki order hint
order_hint = WikiOrderHint(owner_id=project.id).get()

You'll notice the output looks like:

WikiOrderHint(owner_id='...', owner_object_type='ENTITY', id_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:

# As you can see from the printed message, the order hint is not set by default, so you need to set it explicitly at the beginning.
order_hint.id_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,
]
order_hint.store()

You'll notice the output shows the updated order:

WikiOrderHint(id_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:

# Update wiki order hint
order_hint = WikiOrderHint(owner_id=project.id).get()
order_hint.id_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,
]
order_hint.store()

13. Delete Wiki pages¶

Delete a Wiki page by providing the owner ID and Wiki page ID:

# Delete a wiki page
sub_wiki_6 = WikiPage(
    owner_id=project.id,
    parent_id=root_wiki_page.id,
    title="Sub Page 6 to be deleted",
    markdown=f"# Sub Page 6 to be deleted\n\nThis is a sub page to be deleted.",
).store()
wiki_page_to_delete = WikiPage(owner_id=project.id, id=sub_wiki_6.id).delete()

Source Code for this Tutorial¶

Click to show me

#!/usr/bin/env python3
"""
Tutorial script demonstrating the Synapse Wiki models functionality.

This script shows how to:
1. Create, read, update, and restore wiki pages
2. Create wiki pages from markdown text and files, and download markdown content
3. Create wiki pages with attachments, retrieve attachment handles and URLs, and download attachments and previews
4. Retrieve wiki page hierarchy using WikiHeader
5. Access wiki version history using WikiHistorySnapshot
6. Get, set, and update wiki page ordering using WikiOrderHint
7. Delete wiki pages

"""
import os

from synapseclient import Synapse
from synapseclient.models import (
    Project,
    WikiHeader,
    WikiHistorySnapshot,
    WikiOrderHint,
    WikiPage,
)

syn = Synapse()
syn.login()

# Get the project
project = Project(name="My uniquely named project about Alzheimer's Disease").get()

# Section1: Create, read, and update wiki pages
# Create a new wiki page for the 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.",
).store()

# OR you can create a wiki page with an existing markdown file. More instructions can be found in section 2.
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,
).store()

# Update the wiki page
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,
).store()

# Restore the wiki page to the original version
wiki_page_restored = WikiPage(
    owner_id=project.id, id=root_wiki_page.id, wiki_version="0"
).restore()

# check if the content is restored
assert (
    root_wiki_page.markdown_file_handle_id == wiki_page_restored.markdown_file_handle_id
), "Markdown file handle ID does not match after restore"
assert (
    root_wiki_page.id == wiki_page_restored.id
), "Wiki page ID does not match after restore"
assert (
    root_wiki_page.title == wiki_page_restored.title
), "Wiki page title does not match after restore"

# Get the wiki page
# Once you know the Wiki page id, you can retrieve the Wiki page with the id
retrieved_wiki = WikiPage(owner_id=project.id, id=root_wiki_page.id).get()

# Or you can retrieve the Wiki page with the title
retrieved_wiki = WikiPage(owner_id=project.id, title=root_wiki_page.title).get()

# Check if the retrieved Wiki page is the same as the original Wiki page
assert (
    root_wiki_page.markdown_file_handle_id == retrieved_wiki.markdown_file_handle_id
), "Markdown file handle ID does not match retrieved wiki page"
assert (
    root_wiki_page.id == retrieved_wiki.id
), "Wiki page ID does not match retrieved wiki page"
assert (
    root_wiki_page.title == retrieved_wiki.title
), "Wiki page title does not match retrieved wiki page"

# Create a sub-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.",
).store()

# Section 2: WikiPage Markdown Operations
# Create wiki page from 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,
).store()


# Create a wiki page from a markdown file
markdown_file_path = "~/temp/temp_markdown_file.md.gz"

# Create wiki page from markdown file
sub_wiki_3 = WikiPage(
    owner_id=project.id,
    parent_id=root_wiki_page.id,
    title="Sub Page 3 created from markdown file",
    markdown=markdown_file_path,
).store()

# Download the markdown file
# Note: If the markdown is generated from plain text using the client, the downloaded file will be named wiki_markdown_<wiki_page_title>.md.gz. If it is generated from an existing markdown file, the downloaded file will retain the original filename.
# Download the markdown file for sub_wiki_2 that is created from markdown text
wiki_page_markdown_2_url = WikiPage(
    owner_id=project.id,
    id=sub_wiki_2.id,
).get_markdown_file(
    download_file=False,
)

# Download the markdown file for sub_wiki_2 that is created from markdown text
wiki_page_markdown_2 = WikiPage(
    owner_id=project.id, id=sub_wiki_2.id
).get_markdown_file(download_file=True, download_location=".")

# Download the markdown file for sub_wiki_3 that is created from a markdown file
wiki_page_markdown_3 = WikiPage(
    owner_id=project.id, id=sub_wiki_3.id
).get_markdown_file(download_file=True, download_location=".")

# Section 3: WikiPage with Attachments
# Create a temporary file for the attachment
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 = WikiPage.reformat_attachment_file_name(
    os.path.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=f"# Sub Page 4 with Attachments\n\nThis is a attachment: ${{previewattachment?fileName={attachment_file_name_reformatted}}}",
    attachments=[attachment_file_name],
).store()

# Inlucde images in the markdown file
image_file_path = "path/to/test_image.png"
# use the original file name instead of the gzipped file name for images
image_file_name = os.path.basename(image_file_path)
markdown_content = f"# 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=[image_file_path],
).store()

# Get attachment handles
attachment_handles = WikiPage(
    owner_id=project.id, id=sub_wiki_4.id
).get_attachment_handles()

# Get attachment URL without downloading
wiki_page_attachment_url = WikiPage(
    owner_id=project.id, id=sub_wiki_4.id
).get_attachment(
    file_name=os.path.basename(attachment_file_name),
    download_file=False,
)

# Download an attachment
wiki_page_attachment = WikiPage(owner_id=project.id, id=sub_wiki_4.id).get_attachment(
    file_name=os.path.basename(attachment_file_name),
    download_file=True,
    download_location=".",
)
# Unzip the attachment file
unzipped_attachment_file_path = WikiPage.unzip_gzipped_file(wiki_page_attachment)

# Download an attachment preview. Instead of using the file_name from the attachmenthandle response when isPreview=True, you should use the original file name in the get_attachment_preview request. The downloaded file will still be named according to the file_name provided in the response when isPreview=True.
# Get attachment preview URL without downloading
attachment_preview_url = WikiPage(
    owner_id=project.id, id=sub_wiki_4.id
).get_attachment_preview(
    file_name=os.path.basename(attachment_file_name),
    download_file=False,
)

# Download an attachment preview
attachment_preview = WikiPage(
    owner_id=project.id, id=sub_wiki_4.id
).get_attachment_preview(
    file_name=os.path.basename(attachment_file_name),
    download_file=True,
    download_location=".",
)

# Section 4: WikiHeader - Working with Wiki Hierarchy
# Get wiki header tree (hierarchy)
headers = WikiHeader.get(owner_id=project.id)

# Section 5. WikiHistorySnapshot - Version History
# Get wiki history for root_wiki_page
history = WikiHistorySnapshot.get(owner_id=project.id, id=root_wiki_page.id)

# Section 6. WikiOrderHint - Ordering Wiki Pages
# Set the wiki order hint
order_hint = WikiOrderHint(owner_id=project.id).get()
# As you can see from the printed message, the order hint is not set by default, so you need to set it explicitly at the beginning.
order_hint.id_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,
]
order_hint.store()

# Update wiki order hint
order_hint = WikiOrderHint(owner_id=project.id).get()
order_hint.id_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,
]
order_hint.store()

# Delete a wiki page
sub_wiki_6 = WikiPage(
    owner_id=project.id,
    parent_id=root_wiki_page.id,
    title="Sub Page 6 to be deleted",
    markdown=f"# Sub Page 6 to be deleted\n\nThis is a sub page to be deleted.",
).store()
wiki_page_to_delete = WikiPage(owner_id=project.id, id=sub_wiki_6.id).delete()

Wikis¶

Tutorial Purpose¶

Prerequisites¶

1. Create a Wiki page¶

Initial setup¶

2. Update a Wiki page¶

3. Restore a Wiki page to a previous version¶

4. Get a Wiki page¶

5. Create a sub-Wiki page¶

6. Create a Wiki page from markdown¶

Create a Wiki page directly from a string:¶

Create a Wiki page from a markdown file¶

7. Download Wiki page markdown¶

Download the markdown file URL for a Wiki page¶

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¶

Download the markdown file for a Wiki page that is created from a markdown file¶

8. Create Wiki pages with attachments¶

Create a Wiki page with attachments¶

9. Retrieve attachment handles and URLs, and download attachments and previews¶

Get attachment handles¶

Get attachment URL without downloading¶

Download an attachment file¶

Get attachment preview URL¶

Download an attachment preview¶

10. Retrieve Wiki page hierarchy using WikiHeader¶

Get Wiki header tree¶

11. Access Wiki version history using WikiHistorySnapshot¶

Get Wiki history¶

12. Get, set, and update Wiki page ordering using WikiOrderHint¶

Get the current order hint¶

Set the Wiki order hint¶

Update Wiki order hint¶

13. Delete Wiki pages¶

Source Code for this Tutorial¶

References¶

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`¶