Modernize documentation site with Hakyll and Bulma CSS #49

tmcgilchrist · 2025-11-06T00:20:37Z

This commit migrates the Cloud Haskell documentation site from Jekyll to Hakyll with a modern design using Bulma CSS framework.

Migrated from Jekyll (Ruby) to Hakyll (Haskell)
Added site.hs with comprehensive routing and context handling
Added site.cabal for dependency management
Replaced Bootstrap with Bulma CSS framework
Modern, responsive design inspired by Tokio.rs and Irmin.org
Nord-inspired color scheme for better readability
Custom CSS with improved typography and spacing
Enhanced code syntax highlighting
Hero section on homepage with gradient background
Feature cards highlighting key Cloud Haskell capabilities
Responsive sidebar navigation for documentation
Modern blog layout with card-based design
Improved tutorial pages with breadcrumb navigation
Mobile-friendly responsive design

Created new Bulma-based templates:

templates/default.html - Main layout with navbar and footer
templates/index.html - Homepage with hero and feature cards
templates/documentation.html - Docs with sidebar navigation
templates/tutorial.html - Tutorial pages with breadcrumbs
templates/post.html - Individual blog posts
templates/blog.html - Blog listing page
templates/page.html - Generic pages
Renamed _posts/ to posts/ (Hakyll convention)
Archived old Jekyll layouts to old_layouts/
Archived old includes to old_includes/
Added templates/ directory for new templates
Enhanced css/ with custom.css and syntax.css
Added README-BUILD.md with detailed build instructions
Updated README.md with overview and quick start
Added MIGRATION.md documenting all changes
Added Makefile.new with convenient build targets
Added .github/workflows/deploy.yml for automated deployment
Configured GitHub Actions to build and deploy to GitHub Pages
Includes caching for faster builds

All existing content has been preserved:

Blog posts migrated to posts/ directory
Tutorials remain in tutorials/
Documentation and other pages unchanged
All static assets (images, PDFs) preserved
Clean, modern navigation with dropdown menus
Sticky sidebar for documentation (desktop)
Hover effects on cards and links
Smooth scrolling and transitions
Consistent spacing and typography
Accessible color contrast
Print-friendly styles

This modernisation keeps the existing content while updating the styling and web frameworks used so this will be more maintainable in future and improve the overall user experience.

I've used Claude.ai to generate the CSS and migrate the content. I'm no designer but it looks better and wouldn't have got done without using that tool.

What I haven't done:

Validation of the Haskell code or integrating the snippets from the project.
Fixing links within the tutorial or improving the content there.
Rewriting any of the technical content

Opening this as an early draft to gather feedback.

This commit migrates the Cloud Haskell documentation site from Jekyll to Hakyll with a modern design using Bulma CSS framework. - Migrated from Jekyll (Ruby) to Hakyll (Haskell) - Added site.hs with comprehensive routing and context handling - Added site.cabal for dependency management - Replaced Bootstrap with Bulma CSS framework - Modern, responsive design inspired by Tokio.rs and Irmin.org - Nord-inspired color scheme for better readability - Custom CSS with improved typography and spacing - Enhanced code syntax highlighting - Hero section on homepage with gradient background - Feature cards highlighting key Cloud Haskell capabilities - Responsive sidebar navigation for documentation - Modern blog layout with card-based design - Improved tutorial pages with breadcrumb navigation - Mobile-friendly responsive design Created new Bulma-based templates: - templates/default.html - Main layout with navbar and footer - templates/index.html - Homepage with hero and feature cards - templates/documentation.html - Docs with sidebar navigation - templates/tutorial.html - Tutorial pages with breadcrumbs - templates/post.html - Individual blog posts - templates/blog.html - Blog listing page - templates/page.html - Generic pages - Renamed _posts/ to posts/ (Hakyll convention) - Archived old Jekyll layouts to old_layouts/ - Archived old includes to old_includes/ - Added templates/ directory for new templates - Enhanced css/ with custom.css and syntax.css - Added README-BUILD.md with detailed build instructions - Updated README.md with overview and quick start - Added MIGRATION.md documenting all changes - Added Makefile.new with convenient build targets - Added .github/workflows/deploy.yml for automated deployment - Configured GitHub Actions to build and deploy to GitHub Pages - Includes caching for faster builds All existing content has been preserved: - Blog posts migrated to posts/ directory - Tutorials remain in tutorials/ - Documentation and other pages unchanged - All static assets (images, PDFs) preserved - Clean, modern navigation with dropdown menus - Sticky sidebar for documentation (desktop) - Hover effects on cards and links - Smooth scrolling and transitions - Consistent spacing and typography - Accessible color contrast - Print-friendly styles This modernisation keeps the existing content while updating the styling and web frameworks used so this will be more maintainable in future and improve the overall user experience.

The previous code highlighting had poor contrast - grey blocks made Haskell code unreadable. This commit fixes the styling: ## Changes ### Code Block Improvements - Set explicit light text color (#d8dee9) on dark background (#3b4252) - Added proper contrast for all code elements - Enhanced visual separation with subtle border and shadow - Improved line-height (1.6) for better readability - Added margin spacing around code blocks ### Inline Code Styling - Light background (#f5f5f5) with red accent (#bf616a) - Clear distinction from block code - Medium font-weight (500) for emphasis - Proper padding and border-radius ### Syntax Highlighting Colors (Nord-inspired) - Keywords: #81a1c1 (blue, bold) - Types: #8fbcbb (cyan) - Strings: #a3be8c (green) - Functions: #88c0d0 (light cyan) - Comments: #616e88 (grey, italic) - Numbers: #b48ead (purple) - Operators: #81a1c1 (blue) ### Technical Details - Handles multiple Pandoc output formats (.sourceCode, div.sourceCode) - Plain code blocks (without syntax) also styled consistently - Font stack: "Fira Code", Monaco, Consolas, Courier New, monospace - All code elements properly inherit colors when nested ### Files Modified - css/custom.css: Base code block styling - css/syntax.css: Syntax highlighting colors and classes - code-test.md: Test page to verify styling (can be removed) The new styling provides excellent contrast and readability while maintaining the modern, Nord-inspired aesthetic of the site.

Jekyll's {% highlight %} syntax is not recognized by Hakyll/Pandoc. This commit converts all 133 code blocks to use standard Markdown code fences (```lang) for proper syntax highlighting. ## Changes ### Conversion Applied - Replaced `{% highlight <lang> %}` with ````<lang>` - Replaced `{% endhighlight %}` with ```` - Total: 133 code blocks converted across 12 files ### Files Converted **Tutorials (6 files):** - tutorials/1ch.md - Getting Started - tutorials/2ch.md - Managing Topologies - tutorials/3ch.md - Getting to know Processes - tutorials/4ch.md - Managed Processes - tutorials/6ch.md - Advanced Managed Processes - tutorials/tutorial-NT2.md - Programming with Network.Transport **Documentation (2 files):** - documentation.md - Main documentation - wiki.md - Wiki index **Wiki Pages (4 files):** - wiki/networktransport.md - wiki/contributing.md - wiki/newtransports.md - wiki/newdesign.md ### Impact Hakyll uses Pandoc for Markdown processing, which recognizes: - ````haskell` - Haskell code blocks (majority of conversions) - ````bash` - Shell commands - Plain ``` - Generic code blocks These will now be properly syntax highlighted using the Nord-inspired color scheme defined in css/syntax.css. ### Verification Before: 133 instances of {% highlight %} After: 0 instances of {% highlight %} All code blocks now use standard Markdown syntax compatible with Pandoc's syntax highlighting engine.

LaurentRDC · 2025-11-06T00:24:16Z

Exciting!

Changed inline code from red accent to blue primary colors to better match the overall site design and create a more cohesive look. ## Changes ### Color Update - **Before**: Red accent (#bf616a) on light grey background - **After**: Dark blue (#4c6a8f) on light blue background ### New Styling - Background: `#e8f0f8` (light blue, complementary to site theme) - Text: `#4c6a8f` (dark blue, matches --primary-dark) - Border: `#d0dde9` (subtle blue-grey for definition) - Font weight: 500 (medium, for readability) ### CSS Variables Added new CSS custom properties for maintainability: - `--inline-code-bg`: #e8f0f8 - `--inline-code-color`: #4c6a8f - `--inline-code-border`: #d0dde9 ### Files Modified - css/custom.css: Updated inline code styling and added variables - css/syntax.css: Updated :not(pre) > code selector to match - code-test.md: Updated test page with inline code examples ### Design Rationale The new inline code styling: - Complements the primary blue (#5e81ac) used in navigation and hero - Matches the blue gradient used throughout the site - Provides excellent contrast and readability - Creates visual consistency with the Nord-inspired color palette - Distinguished from code blocks while maintaining cohesion Inline code now feels like a natural part of the site's design rather than a contrasting accent element.

LaurentRDC

Overall this looks great! Very beautiful redesign.

LaurentRDC · 2025-11-09T01:17:59Z

css/custom.css

+.hero.is-primary {
+  background: linear-gradient(135deg, #5e81ac 0%, #88c0d0 100%);
+}


I think the hero section should be a shade of purple, to match the Haskell logo. What do you think?

LaurentRDC · 2025-11-09T01:19:24Z

templates/index.html

+<!-- Recent Blog Posts -->
+$if(posts)$
+<section class="section">
+  <div class="container">
+    <h2 class="title is-2 has-text-centered mb-6">Latest Updates</h2>
+    <div class="columns is-multiline">
+      $for(posts)$
+      <div class="column is-4">
+        <div class="card">
+          <div class="card-content">
+            <p class="subtitle is-6 has-text-grey">$date$</p>
+            <h3 class="title is-5">
+              <a href="$url$">$title$</a>
+            </h3>
+          </div>
+        </div>
+      </div>
+      $endfor$
+    </div>
+    <div class="has-text-centered mt-5">
+      <a href="/blog.html" class="button is-primary">View All Posts</a>
+    </div>
+  </div>
+</section>
+$endif$


I think this section should be removed.

These posts are outdated, which makes the project look dead.

LaurentRDC · 2025-11-09T01:22:26Z

tutorials/1ch.md

+```haskell
 import Network.Transport.TCP (createTransport, defaultTCPParameters)
 import Control.Distributed.Process
 import Control.Distributed.Process.Node
-{% endhighlight %}
+```


Is there a reason the code highlighting has all these lines?

LaurentRDC · 2025-11-09T01:24:27Z

site.hs

+    -- Build tags from posts
+    tags <- buildTags "posts/**" (fromCapture "tags/*.html")
+
+    -- Process blog posts
+    match "posts/**" $ do
+        route $ setExtension "html"
+        compile $ pandocCompiler
+            >>= loadAndApplyTemplate "templates/post.html"    postCtx
+            >>= loadAndApplyTemplate "templates/default.html" (postCtxWithTags tags)
+            >>= relativizeUrls
+
+    -- Create post list
+    create ["blog.html"] $ do
+        route idRoute
+        compile $ do
+            posts <- recentFirst =<< loadAll "posts/**"
+            let archiveCtx =
+                    listField "posts" postCtx (return posts) `mappend`
+                    constField "title" "Blog"                `mappend`
+                    constField "page-type" "blog"            `mappend`
+                    defaultContext
+
+            makeItem ""
+                >>= loadAndApplyTemplate "templates/blog.html"    archiveCtx
+                >>= loadAndApplyTemplate "templates/default.html" archiveCtx
+                >>= relativizeUrls


I think the whole concept of the blog should go away. These posts got outdated very quickly.

LaurentRDC · 2025-11-09T01:26:35Z

templates/default.html

+            <a class="navbar-item" href="/blog.html">
+              Blog
+            </a>


I think this should be removed

LaurentRDC · 2025-11-09T01:27:25Z

templates/default.html

+
+        <div id="navbarMenu" class="navbar-menu">
+          <div class="navbar-end">
+            <a class="navbar-item" href="/">


I don't know if GitHub Pages will redirect / to /index.html? Might as well specify /index.html here

LaurentRDC · 2025-11-09T01:29:13Z

templates/default.html

+            <a class="navbar-item" href="/contact.html">
+              Contact
+            </a>


The contact page is also extremely outdated. This should probably be removed (and added back later in some form or another)

claude added 3 commits November 6, 2025 10:53

LaurentRDC reviewed Nov 9, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Modernize documentation site with Hakyll and Bulma CSS #49

Modernize documentation site with Hakyll and Bulma CSS #49

Uh oh!

tmcgilchrist commented Nov 6, 2025

Uh oh!

LaurentRDC commented Nov 6, 2025

Uh oh!

LaurentRDC left a comment

Uh oh!

LaurentRDC Nov 9, 2025

Uh oh!

LaurentRDC Nov 9, 2025

Uh oh!

LaurentRDC Nov 9, 2025

Uh oh!

LaurentRDC Nov 9, 2025

Uh oh!

LaurentRDC Nov 9, 2025

Uh oh!

LaurentRDC Nov 9, 2025

Uh oh!

LaurentRDC Nov 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Modernize documentation site with Hakyll and Bulma CSS #49

Are you sure you want to change the base?

Modernize documentation site with Hakyll and Bulma CSS #49

Uh oh!

Conversation

tmcgilchrist commented Nov 6, 2025

Uh oh!

LaurentRDC commented Nov 6, 2025

Uh oh!

LaurentRDC left a comment

Choose a reason for hiding this comment

Uh oh!

LaurentRDC Nov 9, 2025

Choose a reason for hiding this comment

Uh oh!

LaurentRDC Nov 9, 2025

Choose a reason for hiding this comment

Uh oh!

LaurentRDC Nov 9, 2025

Choose a reason for hiding this comment

Uh oh!

LaurentRDC Nov 9, 2025

Choose a reason for hiding this comment

Uh oh!

LaurentRDC Nov 9, 2025

Choose a reason for hiding this comment

Uh oh!

LaurentRDC Nov 9, 2025

Choose a reason for hiding this comment

Uh oh!

LaurentRDC Nov 9, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants