fontra / fontra/fontra-docs-redesign

[discussion] Site generator options?

Open
#1 7 comments 0 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
1
Forks
0
PR merge metrics
No merged PRs in 30d

Description

Currently, [fontra-docs](https://github.com/fontra/fontra-docs) is built with Jekyll. This is a Ruby-based static site generator, which, in my option, is a little dated and always brings me great pain to install and run locally.

On the other hand, [fontra-blog](https://github.com/fontra/fontra-blog) is built with the JS-based [11ty](https://www.11ty.dev/) static site generator. This is easy to set up with npm, but also has a bit of a learning curve.

Both use .md files for sources, but I bet there are tons of differences in the details, especially with how to set up navigation and/or templating.

Ideally, we would move the documentation to 11ty, as it's more modern and light-weight. Perhaps the magic tooling can be used to convert the Jekyll .md files to 11ty-style.

There may be other viable options to build our docs site from .md files.

(Note: whatever we end up doing, it would be great if existing URLs into docs.fontra.xyz would remain valid, although I'm not opposed to redirecting.)

Contributor guide

No contributing guide indexed for this repository

Research direction

Compare the Jekyll setup in fontra-docs with the 11ty setup in fontra-blog, starting with how each handles Markdown, navigation, and templating. Inventory existing docs URLs and determine whether redirects are needed. Done means documenting a chosen generator and an agreed migration plan that preserves or redirects those URLs.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, jekyll, ruby
Domain
build-system, documentation
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.