search

chuckhoupt / jekyll-apple-help

Easily create Apple Help-Books for your Mac OS X app using this Jekyll template and build system.
MIT License
188 stars 17 forks source link

Evaluating jekyll-apple-help for a help book... #10

Open JamesBucanek opened 8 years ago

JamesBucanek commented 8 years ago

Greetings,

I saw this project announced on the apple-help-authoring list and it looks very promising. It looks, however, a little lightweight for my needs, but I'm curious to see if it can be expanded.

I like the idea of jekyll-apple-help because what I really want to have is a single source for my app's help that I can use to produce a bundled help book, an eBook (to put on Apple's iBooks store), a PDF, and possibly a static set of HTML files for my web server.

I have several requirements, but I'm not familiar with jekyll or jekyll-apple-help to understand how these would be accomplished, or how jekyll-apple-help could be extended so they could be accomplished.

  1. Help anchors. My app uses help anchors (help buttons in the app that open specific help topics). I'm not sure how these would be expressed in jekyll-apple-help.
  2. Collapsed sidebars. My help makes extensive use of collapsed sidebars with additional details, information, warnings, and steps to accomplish specific tasks. (I've attached a screenshot of the iTunes help showing a set of collapsable sidebars). For my help book, I'd want these to work the way they are shown here, and for the static PDF and book form, these would be formatted as static sidebars.

I have a lot of other "would be nice to have" features, particularly floating sidebar formatting and such, but these are the big ones.

Please let me know your thoughts and I look forward to working on this project.

James screen shot 2015-12-05 at 11 57 51 am

chuckhoupt commented 8 years ago

Sorry for the delay. Yes, jekyll-apple-help's goal is to be a quick-start kit for creating Apple-Help and doesn't try to address wider documentation issues. It is small enough to allow extension/re-working -- but that requires a good understanding of Jekyll and Apple-Help.

Jekyll itself is very flexible and extensible with a large ecosystem of plugins and themes. I haven't tried creating eBooks from Jekyll, but other have. For example, you might check out @tomjohnson1492's documentation-theme-jekyll. The Jekyll Talk boards are also a good place to look for inspiration/help.

  1. Help Anchors

    Yes, help anchors are supported. There are several example links on the overview page:

    https://github.com/chuckhoupt/jekyll-apple-help/blob/master/JekyllHelp/_English.lproj/overview.md

    An anchor for a page is defined by the "anchor" property in the page's front-matter. For example, the title page has the anchor "title-page":

    https://github.com/chuckhoupt/jekyll-apple-help/blob/master/JekyllHelp/_English.lproj/index.md

  2. Collapsing Sidebars/Sections

    There's no direct behavior/styling support for collapsing sections, so some customization would be required. For page content, Jekyll-apple-help just provides basic styles that roughly match Apple's help styles for standard HTML/Markdown elements (headers, lists, etc).

JamesBucanek commented 8 years ago

Thanks for the feedback, and the links.

I think I might want to dip my toe in the jekyll-apple-help waters next month with the idea of seeing how much work would be required to get it to meet my needs. In the short term, I think I'll just take a pass at my existing HTML as I have a release that needs to get out the door.

I look forward to playing around with this soon!