Creating a link to start a new topic with pre-filled information

:bookmark: This documentation explains how to create a link that starts a new topic in Discourse with pre-filled information.

:person_raising_hand: Required user level: All users

Sometimes you may want to provide users with a link that opens a new topic composer with certain information pre-filled. This can be useful for various use cases including bug report templates, feature requests, or standardized posts.

Constructing the URL

Base URL

To compose a new pre-filled topic with no extra information, you append /new-topic to your site URL, like so:

https://discourse.example.com/new-topic

Clicking on this will open up a blank new topic composer for any logged-in user (if not logged-in, you’ll be prompted to signin/signup before then opening the composer).

Additional Parameters

While a link to open a blank composer can sometimes be useful, the main strength of this feature is the ability to pre-fill the composer with extra information.

To do this, you can add parameters to the base URL:

https://discourse.example.com/new-topic?title=topic%20title&body=topic%20body&category=category/subcategory&tags=email,planned

This will open a composer window pre-filled with topic title, body, category and tags.

Breaking down the link / URL to show the available options, we have:

  • Base URL: https://discourse.example.com/new-topic
  • The ? URL operator to add the different options
  • Topic title: title=topic%20title
  • The &, used each time when including another parameter
  • Body: body=topic%20body
  • The category and subcategory separated by a slash / if you want to include them: category=category/subcategory
  • The tags separated by comma(s) , if you want to include multiple tags: tags=email,planned

Each of the parameters is optional and can be mix and matched depending on your desired end result.

As an alternative to using the category/subcategory name, you can specify a numeric category_id instead, like:

https://meta.discourse.org/new-topic?title=topic%20title&category_id=3

Example

You can try this here on Meta:

https://meta.discourse.org/new-topic?title=topic%20title&body=topic%20body&category=support/wordpress&tags=wordpress

https://meta.discourse.org/new-topic?title=topic%20title&body=topic%20body&category=support/wordpress&tags=wordpress

:exclamation: Though please don’t actually create the topic :slight_smile: For a more hands-on explore of the feature use our demo site, try.discourse.org

Using a pre-filled URL with Featured Links

This feature also supports Featured Links, provided that the body parameter is not also included.

:information_source: The URL must be URL encoded for the link to work.

For example, to create a topic with the following URL https://www.xkcd.com/556, the link will be:

https://meta.discourse.org/new-topic?title=https%3A%2F%2Fwww.xkcd.com%2F556

Best Practices

  • w3Schools HTML URL Encoding Reference is a good resource to find what text characters are encoded as in the URL. If you have a lot of text to add, there is also a text-to-URL converter in the ‘Try It Yourself’ section.
  • Always URL encode the parameters to avoid issues with special characters.
  • If you’re unsure about the category ID, you can check it by looking at the number in the category URL. (eg. https://meta.discourse.org/c/documentation/using-discourse/126)
  • Test the pre-filled links to ensure they work as expected.

:information_source: It is not currently possibly to have a pre-filled link that opens a composer to reply to a specific topic.

Additional Resources

Last edited by @JammyDodger 2024-07-01T19:32:25Z

Check documentPerform check on document:
86 Likes

There is a LOT of technical heavy lifting happening here that makes this a little unacceptable to mortals; I bet we could make a “helper” webpage that allowed people to generate these links easily.

The equivalent of this might be a nifty little project for someone to implement:

import urllib

site = 'meta.discourse.org'
title = '''My special checklist'''
category = 'todo'
tags = ['tag1', 'tag2']

template = '''\
# Important!

Do these things:

[ ] thing one
[ ] thing two
'''

query = urllib.parse.urlencode(dict(
    title =    title,
    category = category,
    tags =     ','.join(tags),
    body =     template,
))
print(f'https://{site}/new-topic?{query}')

prints this link

3 Likes

possible* - I thought docs were a wiki :thinking:

1 Like

This was changed

2 Likes