Using Discourse to host a Knowledge Base


(Pugwash) #1

I want to look at possibly moving our Knowledgebase into Discourse. Markdown is so much nicer than the insane WYSIWYG editor we have on our existing platform. Having this component of our business in Discourse will make it easier for non-technical employees to extend/maintain.

Most of the prerequisites are already there in Discourse that will allow me to achieve this. I just need to create a new category (Knowledgebase) and have a blob of HTML positioned to the left for the menu (binding together all the KB pages and sections). The only other thing is anchored <a name="#1"> tags (our kb articles can be long) which is fully supported.

What would be the best way to bring in the left hand menu? I have considered globally including it with the available HTML customisations, then selectively displaying it with a category specific CSS rule. This however needlessly adds additional payload to all pages, is this therefore plugin territory?

If it’s within my grasp (reasonably proficient in HTML, CSS, JS - No Ruby skills) I will happily create and share a plugin for this use-case.


(Sam Saffron) #2

A very similar topic was posted a few days ago:

Can you start with some visual mockups of the UI changes you are after?


(Pugwash) #3

Apologies, I was searching for “Knowledgebase” (one word), feel free to merge or hide.

I will post a mockup shortly.


(Sam Saffron) #4

Its ok, you can keep this topic for you provided you get some mockups and UX meat in it :wink:


(Pugwash) #5

OK here’s what I’m trying to achieve:

We use our Discourse instance also for general discussion and I am looking to bring the KB content into a category of it’s own and split out the key areas into sub-categories within the parent KB category.

It’s unlikely we’ll have in excess of 30 sub-categories, so hard coding the menu is not a problem. I’m just now trying to figure out the best way to get the menu rendering only under the KB category?

EDIT:

I will also be trying a few things out myself, so I will update this post in due course.


(Tom Newsom) #6

I’d like to +1 this. We also store documentation in Discourse and would make much wider use of subcategories if they were easily accessible and discoverable in this way.

@pugwash, you should consider how your mockup works as you drill down the tree of subsubcategories (should they exist)


(Pugwash) #7

A tree-like menu system would be nice, although for me I’m happy for users to just go straight to the sub-category topic list (ours will only be one level deep).

Having a dynamically generated tree would need some way of configuring limits or deciding which topics to list on very populated sub-categories. If you have 1,000s of KB articles, I guess the tree would either end up highly threaded or very flat requiring a lot of scrolling.

We have something like this on our existing KB (HelpConsole 2012).


(Sam Saffron) #8

The missing piece here is a mockup of what happens when you click on a category.


(Pugwash) #9

I now have a working(ish) sample :tada:

http://community.quickfile.co.uk/c/knowledgebase

Here’s a typical KB article:

Sole Trader Bookkeeping - The Basics

It’s desktop only and still very unrefined!

The biggest problem for me at the moment is figuring out how to stop the menu disappearing when drilling down into the sub-category, I need to do a page reload to get it back again. Still looking at that one.

EDIT 1:

OK putting the markup in the header rather than the footer fixed the disappearing issue in the sub-categories list, but not in the view topic page. E.g. go to this sub-category and click to view the topic “Account size explained”, the menu is lost. Is there are non javascript solution to solving this?

EDIT 2:

When targeting content for specific categories I needed to use body[class*="category-knowledgebase"] rather than body[class^="category-knowledgebase"]. This class name gets swapped around in order with .docker so adding the wildcard fixed the problem with the menu disappearing when viewing a post.

###The HTML:

The following HTML is placed in the footer:

<div class="lnav-box" style="display:none;">
    <div class="lnav-vspacer"></div>
    <ul class="lnav-menu">
        <li class="navhead"><a href="/">Community</a></li>
        <li class="navhead"><a href="/c/knowledgebase">Knowledge Base</a></li>
        <li><a href="/c/knowledgebase/getting-started">Getting Started</a></li>
        <li><a href="/c/knowledgebase/affinity">Affinity</a></li>
        <li><a href="/c/knowledgebase/banking">Banking</a></li>
        .....
    </ul>
</div>

###The CSS

This rule indents the content to make way for the menu when in the knowledge base category or sub-category:

    body[class*="category-knowledgebase"] .list-container,
    body[class*="category-knowledgebase"] .list-controls {
        margin-left: 165px;
    }

This rule reveals the left navigation container when in the knowledge base category or sub-category.

    body[class*="category-knowledgebase"] .lnav-box{
        padding:0;
        display: block !important;
        position: absolute;
        top:0;
        left:0;
        width:160px;
        min-height:100%;
        z-index: 2;
    }

These rules hide the topic meta data and avatar:

body[class*="category-knowledgebase"] .topic-meta-data,
body[class*="category-knowledgebase"] .topic-avatar{
    display:none;
}

The rest simply take care of the <ul> appearance:

    .lnav-menu{
        list-style:none;
        margin: 0;
        padding: 0;
        border: 0;
    }
    
    .lnav-menu .navhead{
       font-weight:400;
       background-color: #efefef;
    }
    
    .lnav-menu > li{
        width:100%;
        border-left: 5px solid #ccc;
        border-bottom: 1pt solid #efefef;
        float: left;
        min-height: 1px;
        line-height: 1em;
        vertical-align: middle;
    }
    
    .lnav-menu > li:first-child{
        padding-top:20px;
    }
    
    .lnav-menu > li:hover{
        border-left: 5px solid #4c7fff;
        background-color: #efefef;
    }
    
    .lnav-menu > li > a{
        color: #808080;
        display: block;
        padding: 7px 20px;
    }
    
    .lnav-vspacer{
        width:165px;
        height:60px;
        background-color: #efefef;
    }
    

###Other configurations

When creating the sub-categories I’ve suppressed these pages from appearing in the main topic list. As mentioned earlier I’m running a general discussion platform and now bringing the KB into it’s own category container. I don’t want the migrated pages popping up in the main list.

Permissions are set for all users to “See”, and moderators to “Create/Reply/See”.


Using Discourse as a internal Knowledge Base / Intranet
Native theme support
Add column on the left with custom html
(Seth) #11

I implemented @Pugwash’s html and css (I had to look at his site for what he didn’t list here), and I’m very happy with it so far. Unfortunately, his styling does not currently cover the mobile css, though I did implement some of it (hiding avatars and the reply count).

I experimented with implementing the menu, but that covers too much screen space. Does it make sense to add an offscreen sidebar through javascript? What would be the best way to do this? Adding in something from NavNav? Is there a better way to add this functionality to Discourse?

I will try experimenting with different js navigations, but I thought I’d ask if anyone could point me in the right direction. If not, I’ll update with how my testing goes.


(Norandom) #12

How did you get the list of the h1 and h2 elements on top of the page, so that the post structure appears on top?

To clarify: you have topic metadata on top of the post, with anchored links. That would be very useful to me.


(Jim Kleiber) #13

Hey! Thank you for doing this, I’m excited to test it out.

I’ve noticed that in the current version of Discourse (or at least what I’m seeing on my screen), the CSS to hide the avatars and meta-data doesn’t work because the columns are called something else. I’ve added the following code and got the columns to disappear.

body[class*="category-knowledgebase"] .posters,
body[class*="category-knowledgebase"] .posts,
body[class*="category-knowledgebase"] .activity
{
    display:none;
}

(Daniel Hollas) #14

This is awesome! :heart_eyes: I wonder whether this could be turned into a theme?

FYI: @Anna_Berns I just came across this wiki layout, we might be interested, but I am not yet sure we’ll be able to get it to our hosted instance.


(Jeff Atwood) #15

@erlend_sh does this relate to any of your efforts to do knowledge base type layouts?