Documentation site using Hakyll

[saurabhnanda]

Desired content structure

• Guides - each guide gets an independent page
  • Chapters - each chapter gets an independent page
    • Sections - each section gets an independent page
      • Sub-sections - subsections do NOT get an independent page

Possible ways of filling out this content structure:

• GUIDE Comparing DB libraries in Haskell
  • CHAPTER Setting up basic DB mappings
    • SECTION Opaleye
      • SUBSECTION Creating the DB
      • SUBSECTION Strange polymorphic records
      • SUBSECTION Different types for reads and writes
    • SECTION HRR
    • SECTION Persisten
  • CHAPTER Setting up advanced DB mappings
    • SECTION Opaleye
    • SECTION HRR
    • SECTION Persisten
  • CHAPTER Inserting rows
    • SECTION Opaleye
    • SECTION HRR
    • SECTION Persisten
• GUIDE Comparing UI libraries in Haskell
  • CHAPTER Basic "Hello world" app
    • SECTION Reflex-FRP
    • SECTION Purescript+Pux
    • SECTION Reflex-React
  • CHAPTER Creating form elements
    • SECTION Reflex-FRP
    • SECTION Purescript+Pux
    • SECTION Reflex-React
  • CHAPTER Form validations
    • SECTION Reflex-FRP
    • SECTION Purescript+Pux
    • SECTION Reflex-React
• GUIDE Comparing Web libraries in Haskell
• GUIDE Building a webapp using X

Desired sitemap

• Homepage - will have some static introductory content, and a list of guides.
• Guide pages - will have some static introductory content, and the list of chapters, along with each chapter's section. Each chapter's section will actually be a separate webpage. However, subsections will be second-level headings within the section page (and not separate pages in their own right).
• Chapter pages - will have some static content and a list of sections
• Section pages - complete content of the section (including all subsections), along with:
  • breadcrumbs
  • quick switcher to jump between various chapters & sections. Reference Guides index on http://guides.rubyonrails.org
  • list of subsections in the sidebar to allow readers to understand the document structure and jump between sections
  • At the end of the section page, link to the next/prev section based on the Chapter's TOC

Other requirements

• Ability to include content of any other partial inside markdown posts. Ref: http://stackoverflow.com/questions/40712920/how-to-use-partials-inside-markdown/40713294#40713294 We will be putting complete code snippet in separate HS files and compiling them as part of the site build process to ensure that they compile properly.
• An extra command, say stack exec site builcode which builds all the referenced/included HS files to ensure that they compile correctly.
• Convert the following Jekyll theme to Hakyll: TODO
• Syntax highlighting for - Haskell, HTML, SQL, Shell anything else?

[saurabhnanda]

@meditans @mgmeier @wz1000 @sras looking for some feedback here. Planning to kickstart the documentation process and finishing off documentation for what we've done till now, before moving on to the next set of things.