Serving large amounts of static HTML using discourse?

dev
1

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 <div> 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"}}

<div id="main-outlet" class="wrap">
  <h1>html goes here</h1>
</div>

{{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
091024×771 111 KB

3 Likes
2

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 .

5 Likes
3

Because our documentation tool spits out static HTML :neutral_face:

4

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

1 Like
5

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?

2 Likes
6

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.

7

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

8

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.

Would your vision be to have a topic created for each revision and the 1000 documents be replies to that post?

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.

9

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.

The HTML returned is quite clean luckily; should be easy to import.

Hiding stuff with CSS is good enough; it’s just to highlight that you “are not” on the forum :slight_smile:

10

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