Custom/Branded HTML structure for articles

14 Comments

  • Jennifer Rowe
    Comment actions Permalink

    Hey Sam,

    We use Oxygen Author. I's an XML authoring tool, and we use DITA format. We output HTML. So the custom CSS I gave you is what controls the styles when we put the HTML in our HC. (That's a lot of acronyms! :)

    2
  • Jennifer Rowe
    Comment actions Permalink

    Hey Sam,

    I think I found the custom CSS...

    .article-body h1 {
    color: #78A300;
    font-size: 24px;
    line-height: 28px;
    margin: 0 0 0 0;
    padding-bottom: 0;
    }
    .article-body h2 {
    color: #78A300;
    font-size: 22px;
    font-weight: bold !Important;
    line-height: 28px;
    margin: 0 0 0 0;
    padding-bottom: 10px;
    text-transform: none;
    }
    .article-body h3 {
    color: #78a300 !important;
    font-size: 20px !important;
    line-height: 28px;
    margin: 0 0 0 0;
    padding-bottom: 10px;
    }
    .article-body h4 {
    color: #78a300 !important;
    font-size: 18px !important;
    line-height: 28px;
    margin: 0 0 0 0;
    padding-bottom: 0;

    1
  • Charles Nadeau
    Comment actions Permalink

    Jennifer asked me to jump in about DITA. I work on her team at Zendesk.

    As she mentioned, we use Author to write the docs in DITA XML, then transform from DITA to HTML for Help Center.

    As you probably know, DITA is an industry-standard for creating and maintaining large documentation sets. I found this pretty good description of the problem it tries to solve (from https://techwhirl.com/what-is-dita/):

    Writing content in Word, email, PowerPoint, WordPress, HTML, InDesign, FrameMaker, or any other format is equivalent to writing on stone tablets. Your content is essentially stuck in that format and dumb as a rock. Dumb content can’t be easily reused or repurposed, and that’s inefficient and costly.

     

    DITA is a way of writing and storing your content so you can manage it like an asset. It leverages XML (eXtensible Markup Language) to make your content intelligent, versatile, manageable, and portable.

     

    For example, content that is in DITA can be published to (and fully branded) PDF, HTML, RTF, PowerPoint, and mobile–all without ever copying and pasting anything between files.

    Apart from the content/format separation, the main benefits for us are:

    • Force us to be disciplined about content structure. A DITA file is XML. If the structure is invalid, the tool won't let us do anything with it.

    • Allow us to move content around easily. We just drag a topic node from one place to another in the structure.

    • Allow us to reuse content by importing the same file in multiple articles.

    • We don't often publish PDFs but when we do, we use the DITA source files.

    But, we don't have any automated HTML transformations or push mechanisms to Help Center. The writer transforms a DITA article, the pastes the HTML source code in the article editor in HC. Not very elegant, I know.

    1
  • Ann Jensen
    Comment actions Permalink

    Thanks for that explanation Charles. Sorry for delay in reply but I am just back to investigating DITA and Zendesk again.

    How would you advise a client of Zendesk with DITA expertise to maximise reuse of documentation content already developed using DITA into Zendesk Help Center?

    Would you recommend the approach that you described above as the most effective approach currently available?

    Any feedback appreciated,

    Regards,

    Ann

    1
  • Jennifer Rowe
    Comment actions Permalink

    Hey Sam,

    I think the difference is KB vs Community. The first one you show is a Community post and the second one is a KB article. 

    We see the same options you are seeing when we post a KB article (the toolbar without the heading styles).

    I do believe that we have some custom CSS to apply styles when we post our articles in HC (our content is authored and formatted in another tool). But I am not the one who can give you details about that. :) I'll see if I can get you more info.

    0
  • Jessie Schutz
    Comment actions Permalink

    Good hustle, JRowe! :)

    0
  • Samantha Flaherty
    Comment actions Permalink

    Only just got round to catching up on this - thanks so much! :D

    Could I be nosey and ask...what tool do you use to author/format your articles? Are you talking like MS Word or something else? 

    0
  • Andrea Saez
    Comment actions Permalink

    You can definitely use CSS to style the KB articles, we've done it. Not just article-body headers but links, text colors, etc. For example, we've got our own CSS for tables. 

    I would never ever ever recommend using MS Word to format anything. Once it's put into what I think is Redactor that they're using, it'll completely screw up. I can't wait for the day when Zendesk API supports pushing from Mou > Github > Zendesk and everything is just perfectly formatted like magic!

    0
  • Wes Drury
    Comment actions Permalink

    I use the Bootstrap framework which both applies CSS and JS.  Thats how I do the accordions inside of the articles, add alerts, add labels, etc.

    0
  • Samantha Flaherty
    Comment actions Permalink

    Thanks all - giving me some great ideas! :)

    0
  • Ann Jensen
    Comment actions Permalink

    Hi Jennifer, I would be very interested in finding out more about how DITA is used with Zendesk. As clients of Zendesk can we leverage our DITA content in our Zendesk instance?

     

    0
  • Nicole - Community Manager
    Comment actions Permalink

    Thanks, Charles. 

    0
  • annflavin
    Comment actions Permalink

    Hi, 

    Can anyone in Zendesk reply to my last message please?

    Regards,

    Ann

    0
  • Dan Kondzela
    Comment actions Permalink

    Hey Ann!

    I'll be frank with you, I don't have the familiarity and expertise that Charles has with DITA and data formatting. That being said, I would defer to his explanation as the most recommended at the moment. I believe that in describing solutions to you he keeps in mind the viability of his suggestions.

    0

Please sign in to leave a comment.

Powered by Zendesk