Documentation? Customization best practices?


(Dogweather) #1

I’m having trouble finding “discourse documentation” in general, but I’m most interested in seeing how I’d customize an installation yet stay upgradable and within the framework’s intended usage.

A simple example: de-emphasizing this text (because I feel that it’s implementation detail):

So my process which I’m having problems doing is:

  • Figure out: is this something that one can change?
  • If it can be changed, then what is the most maintainable and future-proof way?

This applies to all kind of potential customizations.

I.e., a Discourse equivalent of the Wordpress Child Theme docs page. I realize that Wordpress is a much more mature piece of software. But I wanted to put my 2 cents in for this kind of general guidance.


(Dogweather) #2

One idea: create a developers link on the main discourse.org site which points to the GitHub wiki. Set the wiki to publicly writeable, and post a topic about it, encouraging people to contribute their collected knowledge.


(Manthan Mallikarjun) #3

@codinghorror Maybe its time to create proper documentation? I can help.


A community effort to improve Discourse's documentation
(Jeff Atwood) #4

Mainly anything you can do in CSS is quite safe – via Admin, Customize, CSS / HTML. So for those fields you showed in the screenshot, hide them via CSS.


(Manthan Mallikarjun) #5

But what about the second half of the post? Wheres the docs?


(Dogweather) #6

Thanks, Jeff.

But there’s probably better and worse places to add this custom css, right? It sounds to me like you’re saying to just go ahead and put site/local css in the rails stylesheets directory. But that makes me wonder whether a file I place in that directory will be read in because I don’t see an application.css with the usual require_tree . statement. And then, I hope I don’t stamp over some other file, or that a future change would overwrite my custom file.

Have you thought about creating a site or local directory? Or maybe, some directory structure completely out of the discourse directory hierarchy?


(山) #7

A plugin would work for this, yes? The way I see it, the HTML/CSS options in the Customize CP are a shortcut that could also be completed with a plugin. That way, when the forum is rebuilt, the plugin is reapplied.

But as @codinghorror mentioned, just throw your CSS changes into the appropriate spot at Admin -> Customize -> HTML/CSS.


(Dogweather) #8

I didn’t realize there’s a control panel which manages site specific css.


(山) #9

I believe that is explained in the READ ME FIRST: Admin Quick Start Guide which is one of the generated topics for any new Discourse install.


(Dogweather) #10

Thanks, I haven’t yet installed it: I’m evaluating the options for my sites.


(山) #11

I haven’t either. I have a home server and everything else ready for development to deploy but my Real Life is currently in transition (a definite water shed period). But perusing Meta in the meantime has made me adept before giving the admin CP a glance beyond screenshots others have posted of it. :grin: