dcs-discourse-plugin

A Discourse plugin that allows to integrate your website or web app with Discourse. Part of the Docuss solution.

This project is not active anymore. Fixes are provided to existing users, but I stopped working on new features. You might want to check DiscPage, which is somehow a simplified version of Docuss.

Demos

See here.

Discourse Setup

1. Install the plugin in Discourse

The plugin’s repository url is:

https://github.com/sylque/dcs-discourse-plugin.git

Step by step guide, based on Discourse official documentation:

1. Access your Discourse server
2. Type cd /var/discourse
3. Type sudo nano containers/app.yml
4. Arrow down until you see this:

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
           - git clone https://github.com/discourse/docker_manager.git

5. Paste - git clone https://github.com/sylque/dcs-discourse-plugin.git beneath that, so that all together it looks like this:

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
           - git clone https://github.com/discourse/docker_manager.git
           - git clone https://github.com/sylque/dcs-discourse-plugin.git

6. Hit control + O then Enter (to save app.yml)

7. Hit control + X (to exit app.yml)

8. Type sudo ./launcher rebuild app to rebuild Discourse

2. Set Discourse settings

In the Discourse Admin panel, open the Settings page and set those settings:

• tagging enabled → checked
• min trust to create tag → 0: new user
• allow duplicate topic titles → checked
• docuss enabled → checked
• docuss website json file → one or several urls, each one pointing to a json file describing a website or web app. The structure of the file is described here. If you are new to Docuss and just want to see if the plugin works correctly, enter this url: https://sylque.github.io/dcs-client/demos/mustacchio/dcs-website.json. Important note: if your Discourse instance is accessed through HTTPS, then your json files must be accessed through HTTPS also.

If your Discourse instance doesn't use tags (i.e. if tagging enabled was unchecked before you checked it as part of this setup), set this additional setting:

• docuss hide tags → checked

3. Create the required tags

Select a public topic (or create a new one), edit it, and add those two tags:

• dcs-comment
• dcs-discuss

Discourse will ask if you want to create them: answer yes.

Now you can safely delete the topic if you want, the tags will remain. Nope, sometimes it doesn't work. You better keep the topic.

Website Navigation

Now that your website is displayed within Discourse, you might want to reconsider your navigation/menu system. You can keep it in your website, you can move it to Discourse, or you can do a bit of both.

At the very minimum, in your website, you need to update the links to your forum. Change them to http://www.mydiscourse.org/latest (instead of http://www.mydiscourse.org).

Discourse custom navigation is out of the scope of this plugin. To learn more about it, see Best way to customize the header. Just use the fact that, whether from a Discourse menu or from your website:

• http://www.mydiscourse.org/ points to your home page,
• http://www.mydiscourse.org/docuss/[pageName] points to one of your website's page,
• http://www.mydiscourse.org/latest points to your forum.

Additional Plugin Settings

• docuss hide sugg topics: hide suggested topics displayed at the bottom of Docuss topic pages.
• docuss hide categories: hide categories everywhere in Discourse. Notice that you can also set "header dropdown category count" to 0 to hide categories in the hamburger menu alone.
• docuss hide tags: hide tags everywhere in Discourse.
• docuss hide hamburger menu: hide the Discourse hamburger menu.

Category Assignment with URL Composer Templates

When using the url-composer-templates theme component alongside this plugin, category assignment is handled automatically to prevent conflicts:

How It Works

• Template-based forms (e.g., /tags/intersection/* URLs): The url-composer-templates component assigns the "Hidden" category before opening the composer
• Manual composer opens: Users can select categories normally
• Other Docuss pages (e.g., whitepaper): Standard Docuss behavior applies

Default Category for Template Forms

By default, template forms auto-select the "Hidden" category. To change this:

1. Open url-composer-templates/javascripts/discourse/api-initializers/z-auto-open-composer.js
2. Find the section labeled "CATEGORY AUTO-SELECTION FOR TEMPLATE FORMS"
3. Modify the category finder. For example, to use "General" instead:

   const targetCategory = site.categories.find(
     (c) => c && c.name && c.name.toLowerCase() === "general"
   );

Excluding Category Auto-Selection

To disable automatic category selection for template forms:

1. In z-auto-open-composer.js, find the category auto-selection code
2. Comment out or remove the "hidden" category lookup block
3. Set categoryId = null to let users choose manually

This ensures templates work smoothly while maintaining flexibility for different Docuss use cases.

Known limitations when using tags

Docuss relies on automatically generated tags to achieve its magic (generated tags are of the form dcs-xxxxxx-xxxxxx). That is why, to be on the safe side, it is advised not to use tags in your Discourse community and set the above docuss hide tags setting to true. To ease your decision, consider that Docuss is a new way of categorizing topics ("per balloon", instead of "per category" or "per tag"), so maybe tags are unnecessary with Docuss anyway.

However, if you decide to use tags in your Discourse community, Docuss will try its best to hide its automatically generated tags. One area where Docuss doesn't do a good job is the tags page, where Docuss tags will appear blank instead of being hidden.

As an administrator, when troubleshooting tag issues, press Alt+a to disable Docuss CSS and thus showing Docuss tags.

FAQ

When I create a topic for a Docuss page, the category field is hidden. Why is that?

User cannot select a category from a Docuss page. Categories are applied automatically by Docuss, depending on webmaster predefined choices. The way webmasters define categories depends on the Docuss Client library they use:

• comToPlugin.js: see here
• dcs-html-based.js: see here
• dcs-decorator.js: see here (search the page for "category")

Debug Timing System

A cross-origin timing diagnostic tool for tracking communication between Discourse (Docuss plugin) and the embedded iframe. Use this to debug timing issues, identify slow operations, and understand the sequence of events during page navigation.

Quick Start

Open your browser's developer console (F12 → Console) and run:

// Start collecting for 24 hours
window.dcsTimingStart(24)

// Navigate around your site normally...

// Check status anytime
window.dcsTimingStatus()

// When done, stop and download the log
window.dcsTimingStop()

Features

• Persists across page reloads - Collection continues when you refresh or navigate
• Auto-saves every 5 seconds to localStorage
• Saves on page unload - Won't lose data if you close the tab
• Auto-expires after the specified duration
• Caps at 10,000 events to prevent localStorage overflow
• Trims oldest events automatically if storage gets full

Available Commands

Command	Description
dcsTimingStart(hours)	Start collecting for specified hours (default 24)
dcsTimingStatus()	Check if active, time remaining, event count
dcsTimingStop()	Stop collecting and download all events
dcsTimingExport()	Download collected events without stopping
dcsShowTimeline()	Show events in console
dcsTimingClear()	Delete all collected data

What Gets Tracked

Discourse Side:

• Route changes - When Discourse navigates to a new page
• Page loads - When iframe content is loaded
• Tag loading - When waiting for topic tags to load
• postMessage sends - Messages sent to the iframe

iframe Side (fl-maps):

• Message received - When iframe receives a message from parent
• pauseVideo - Video pause events
• dcsOpenForm - Form open requests
• dcs-topic-posted - Topic creation confirmations
• Map mount - When the map component mounts

Example Log Output

DCS Timing Log - Extended Collection
=====================================
Exported: 2025-12-11T10:30:00.000Z
Collection started: 2025-12-10T10:30:00.000Z
Duration: 1440.0 minutes
Total events: 523

=== PAGE: https://example.com/docuss/home ===
     0ms (10:30:00.123) [discourse] Route change detected
    15ms (10:30:00.138) [discourse] iframe ready for transitions
    45ms (10:30:00.168) [fl-maps] Message received: cycleRoutes

Workflow for Bug Reports

1. Run dcsTimingStart(24) in console
2. Use the site normally (refresh, navigate, reproduce issues)
3. Run dcsTimingStatus() to check event count
4. Run dcsTimingStop() to download the log file
5. Share the .txt file for analysis

License

See here.