Hi, Currently we have a few thousand pages of documentation in static HTML files. We need a place to store this and render them. Our initial instinct was to use wordpress and use a mass-import; then link discourse and wordpress using the plugin etc. But… we kind of had a brainwave.. what if we used Discourse to serve these files? We dump the HTML files in a folder and write a bit of Ruby to fetch the correct from the html file and render it in a Handlebar template. This would have several advantages: No need for extensive SSO (some documents will only be visible to certain discourse-groups / TLs), we’ll have access to the Discourse users out of the box Consistent look and feel, since we can render the Discourse menu on top etc. A single CSS file can be used. A single URL, keeps everything nice and clean It’s faster than Wordpress one tech stack, just Ember/RoR; no added PHP knowledge required Some downsides I can foresee: prone to breaking, means we’ll have to properly test our solution with every Discourse release bad for SEO, this is fine, we’re behind a login anyway I’d love to hear if this is a terribly bad idea :slight_smile: Otherwise I’ll see if I can turn this into a plugin of sorts. Something like this: {{plugin-outlet name="above-site-header"}} {{site-header canSignUp=canSignUp showCreateAccount=(route-action "showCreateAccount") showLogin=(route-action "showLogin") showKeyboard=(route-action "showKeyboardShortcutsHelp") toggleMobileView=(route-action "toggleMobileView") toggleAnonymous=(route-action "toggleAnonymous") logout=(route-action "logout")}} {{plugin-outlet name="below-site-header"}} html goes here {{plugin-outlet name="above-footer" args=(hash showFooter=showFooter)}} {{#if showFooter}} {{custom-html name="footer"}} {{/if}} {{plugin-outlet name="below-footer" args=(hash showFooter=showFooter)}} {{outlet "modal"}} {{topic-entrance}} {{outlet "composer"}} [09]

What I would do is to write an importer to pull them in. I don’t understand why you’d have trouble in the future unless you plan to continue creating static html files to import,but i don’t know why you’d do that .

Because our documentation tool spits out static HTML :neutral_face:

That’s sad. Can you fix that tool, or is it something you don’t have control over? Anyway, it seems like your solution is working for you, but my inclination would be to write a script that pumped the stuff into Discourse via the API. You wouldn’t need to worry about plugins breaking (API changes relatively slowly).

Thank you for the suggestion. I’m afraid it won’t work, since the tool is heavily used (and liked) by the documentation team. To create such a plugin is beyond my capabilities, how does that generally work? Simply post the specs to the marketplace and ask for a quote?

My suggestion was to modify your tool rather than replace it. Can you modify it, or is it immutable? Yes, you can post in #marketplace. I think that you want not a plugin, but a script that uses the API to post new files as they are created.

The tool is modifiable, but it will always output static stuff (documentation is written in XML and outputted using several XSLTs). Our documentation is versioned and contains ~1000 documents per version; since we have a set of documents for every minor version (one released every 6 weeks or so), I’m afraid an import won’t work all that well. But, I am very happy to be proven wrong. If we go the import-and-display-as-thread route, then we’ll need some extensive modification to add the left-hand navigation and remove some discourse specific things (e.g. remove the post-date, remove the author, remove the reply button). I’m a bit at a loss as to how we can best make this decision, we will probably need to get an experienced Discourse dev involved (I’m OKish with technology, but the Discourse stack is quite big).

[image] Bas: The tool is modifiable, but it will always output static stuff (documentation is written in XML and outputted using several XSLTs). That’s fine. It should then be easy to have it spit out something that will work with Discourse’s markdown engine and have it make the API call to post it in addition to writing the file to wherever it writes it. [image] Bas: Our documentation is versioned and contains ~1000 documents per version; since we have a set of documents for every minor version (one released every 6 weeks or so), Would your vision be to have a topic created for each revision and the 1000 documents be replies to that post? [image] Bas: If we go the import-and-display-as-thread route, then we’ll need some extensive modification to add the left-hand navigation and remove some discourse specific things (e.g. remove the post-date, remove the author, remove the reply button). I don’t see the problem with some user being who owns the document, though I suppose you could hide the username with CSS. Similarly, it would seem like the documents were created on a date and that knowing the date that they were produced would be helpful. Again, you could probably hide the dates with CSS. Removing the reply button is as easy as changing the category permissions so that people can’t reply.

[image] pfaffman: Would your vision be to have a topic created for each revision and the 1000 documents be replies to that post? No, we really would need a coherent set of documents; customers will use a specific version for a year or so (so often they are 5 versions or so behind), they will need to have access to a canonical set of documentation. Currently we have urls of the form example.com/documentation/product/version/setup.html I can see us creating a category for each product, with a subcategory for each version; could keep search manageable as well. [image] pfaffman: That’s fine. It should then be easy to have it spit out something that will work with Discourse’s markdown engine and have it make the API call to post it in addition to writing the file to wherever it writes it. The HTML returned is quite clean luckily; should be easy to import. [image] pfaffman: Similarly, it would seem like the documents were created on a date and that knowing the date that they were produced would be helpful. Again, you could probably hide the dates with CSS. Removing the reply button is as easy as changing the category permissions so that people can’t reply. Hiding stuff with CSS is good enough; it’s just to highlight that you “are not” on the forum :slight_smile:

Serving large amounts of static HTML using discourse?

Development

Bas (Bas van Leeuwen) August 17, 2017, 8:02am 10

Do you by chance know of a public Discourse install that has so extensively modified its content structure @pfaffman?

Topic		Replies	Views
Custom Platform Development	16	660	November 25, 2024
Converting discourse topics to read only pages Product Support	1	1298	September 8, 2017
Is anyone here using their Discourse instance as their entire website? Community Building	17	5199	March 4, 2021
A basic Discourse archival tool Development	24	15230	April 30, 2025
We built a static blog with Discourse as the backend Praise	5	4717	September 11, 2015

Serving large amounts of static HTML using discourse?

Related topics