Reduce the number of Pages Templates
We are currently not very good at maintaining and updating the GitLab Pages template repositories. Right now, we don't update them on our own initiative unless a team or community member happens to take the time to submit an MR.
Maintaining them properly would take a considerable amount of engineering time that would not be available to feature development. I'd wager that templates aren't that important to users.
Most of the modern Static Site frameworks offer their own CLI users use to get started. Many users will thus create a repository from scratch and then (maybe) use the templates only as a point of reference to integrate GitLab CI. With the Pages Wizard we even introduced a very comfortable interactive workflow to replace even the need for that.
At this time we have 45 templates in our template repository that we maintain and bundle 14 of them with Gitlab. Most of the template in the gitlab.com/pages group use niche frameworks that aren't particularly widely used. The selection we're bundling seems to be a very weird, horribly outdated sub-selection of them with no particular selection criteria.
The Goal
We should reduce the number of repositories we actively maintain to a minimum to keep the workload manageable. In addition, the quality of the few bundled templates should significantly increase.
Proposal
I'd propose to introduce the differentiation between "verified" and unverified templates, signified by a to-be created badge on the repository.
There will be no more than 10 (TBD) "verified" templates at a given time. We create a process around keeping those up-to-date. I'll investigate how much this process can be automated.
Unverified templates stay there as a resource for the community. We may accept MRs, but they are not actively maintained on our initiative and there is no SLO on those MR reviews.
Going forward, the verified templates are the only ones we bundle. This selection criteria will also apply for the `.gitlab-ci.yml` templates.
Selection criteria
We'll need a defined selection criteria to make that selection. It should be easy to document so we can revisit and update the selection list in the future.
Preselection
Eligibility Criteria
To be up for consideration, the selected Frameworks must:
- target Pages as the deployment platform (This will exclude the Netilfy templates)
- not be deprecated (e.g. Sapper)
Realms
Because — for example — JS developers are unlikely to pick a Ruby Static site generator we want to have at least one Framework template of the following "Realms":
- Plain HTML
- Markdown*
- React
- Vue
- Go
- Ruby
*Markdown is a rather large category for Static site generators so we consider multiple frameworks.
Scoring
To select a framework for each realm, a scoring model is used and the highest scoring frameworks is selected.
The score is based on the following values:
-
GitLab Stars
As a vector for how popular a certain template is with our users
-
GitHub Stars
As a vector for how popular a certain framework is in general
-
Jamstack Community Survey Satisfaction Score
As a vector for how likely a certain framework will be picked to start a new project.
-
Jamstack Community Survey Usage Score
As a vector for how many people have used this framework before and are therefore likely to pick it again
-
Pages Suitability Score
As a vector for how useful this template is in connection with GitLab Pages
- 0 - The Framework does not produce static sites, needs a runtime
- 1 - The Framework can be configured to produce static sites
- 2 - The Framework natively produces static sites
Total Score
The total score is calculated by dividing each of the score's value by the maximum value of that column to get a fraction of 1 (the row with the highest value gets 1). See the formula below:
with:
- g = GitLab Stars
- h = Github Stars
- u = Jamstack Community Survey Usage Score*
- s = Jamstack Community Survey Satisfaction Score*
- p = Pages Suitability Score
\* if the framework is not included in the survey, the average value of all frameworks was used instead
Total = \frac{g}{max(G)} + \frac{g}{max(G)} + \frac{u}{max(U)} + \frac{s}{max(S)} + \frac{p}{max(P)}
The current list
This is a list of templates we currently maintain:
Repo | Currently Bundled with GitLab? | Stars on GitLab | Last updated | GitHub Stars | JCS Usage Score | JCS Satisfaction Score | Pages Suitability Score | Total Score | Note |
---|---|---|---|---|---|---|---|---|---|
Bridgetown | 1 | 1 month ago | 1100 | - | - | 2 | 1.90 | ||
astro | ( |
16 | 4 weeks ago | 42500 | 11% | 4.5 | 2 | 2.63 | *as a top level template, not sure who maintains this? |
eleventy | 5 | 10 months ago | 16200 | 19% | 3.8 | 2 | 2.4 | ||
jupyterbook | 11 | 1 year ago | 11200 | - | - | 1 | 1.5 | ||
Courseware | 3 | 2 years ago | ? | - | - | 0 | 0.9 | ||
sapper | 6 | 3 years ago | 7000 | - | - | n/a | - | deprecated, replaced by SvelteKit | |
neocities | 4 | 3 years ago | 1300 | - | - | 2 | 1.91 | ||
swaggerui | 0 | 4 years ago | 25600 | - | - | 1 | 1.60 | ||
docusaurus | 48 | 1 month ago | 52900 | 7% | 2.5 | 2 | 2.26 | ||
emscripten | 6 | 2 years ago | 25200 | - | - | 0 | 1.11 | Webassembly Compiler? Is that really what Pages is about? | |
nfhexo | 3 | 3 years ago | 38500 | - | - | - | Netlify integration example | ||
nfgitbook | 11 | 1 year ago | 26400 | - | - | - | Netlify integration example | ||
nfplain-html | 10 | 3 months ago | - | - | - | - | Netlify integration example | ||
nfjekyll | 5 | 4 years ago | 48300 | - | - | - | Netlify integration example | ||
nfhugo | 13 | 2 months ago | 72600 | - | - | - | Netlify integration example | ||
vuepress | 51 | 1 year ago | 22400 | 8% | 1.7 | 2 | 1.86 | ||
frozen-flask | 13 | 4 days ago | 781 | - | - | 1 | 1.43 | ||
emacs-reveal | 32 | 1 year ago | 53 | - | - | 0 | 0.97 | ||
gatsby | 70 | 3 months ago | 55000 | 28% | 0.9 | 1 | 1.93 | ||
jigsaw | 9 | 1 year ago | 2100 | - | - | 2 | 1.93 | ||
nuxt | 62 | 3 months ago | 52000 | 22% | 2.7 | 1 | 2.15 | ||
MkDocs | 95 | 6 days ago | 18300 | - | - | 2 | 2.28 | ||
org-mode | 72 | 11 months ago | N/A | - | - | 1 | 1.57 | ||
sphinx | 96 | 11 months ago | 6000 | - | - | 1 | 1.68 | ||
zim | 11 | 1 year ago | 1900 | - | - | 1 | 1.43 | ||
ikiwiki | 13 | 2 years ago | N/A | - | - | 2 | 1.92 | ||
hakyll | 28 | 2 years ago | 2600 | - | - | 2 | 1.98 | Haskell SSG | |
nikola | 18 | 2 years ago | 2600 | - | - | 2 | 1.96 | ||
gitbook | 163 | 6 months ago | 26400 | - | - | 2 | 2.52 | ||
octopress | 4 | 2 years ago | 1700 | - | - | 2 | 1.92 | Deploying Jekyll blogs | |
doxygen | 27 | 10 months ago | 5400 | - | - | 1 | 1.00 | Niche documentation tool, mostly for C++ | |
nanoc | 14 | 2 years ago | 2100 | - | - | 2 | 1.94 | ||
pelican | 60 | 3 weeks ago | 12300 | - | - | 2 | 2.14 | ||
hyde | 9 | 2 months ago | 318 | - | - | 2 | 1.92 | Specifically for documenting C++ | |
lektor | 4 | 2 years ago | 3800 | - | - | 2 | 1.93 | ||
hexo | 122 | 1 year ago | 38500 | - | - | 2 | 2.52 | ||
brunch | 7 | 2 years ago | 6800 | - | - | 0 | 0.97 | ||
metalsmith | 12 | 2 years ago | 7800 | - | - | 2 | 1.99 | ||
harp | 6 | 2 years ago | 5000 | - | - | 2 | 1.95 | ||
hugo | 399 | 2 hours ago | 72600 | 13% | 1.2 | 2 | 3.14 | ||
jekyll-branched | 13 | 2 months ago | - | - | - | - | - | Example for readme-only jekyll repo, pages is in a separate branch. Nice demo, but hardly a template? | |
middleman | 17 | 5 months ago | 7000 | - | - | 2 | 1.99 | ||
plain-html | 294 | 2 weeks ago | - | - | - | 2 | - | ||
jekyll | 269 | 2 weeks ago | 48300 | 14% | 0.4 | 2 | 2.46 |
Not currently available as a template, but considered
Repo | GitHub Stars | JCS Usage Score | JCS Satisfaction Score | Pages Suitability Score | Total Score | Note |
---|---|---|---|---|---|---|
Next.js | 121000 | 47% | 4.2 | 1 | 3.43 | |
sveltekit | 17800 | 15% | 4.0 | 1 | 1.86 | |
preact | 36100 | 12% | 2.0 | 1 | 1.50 | |
Gridsome | 8500 | 7% | 0.8 | 2 | 1.40 |
The final selection
Realm | Framework | Score |
---|---|---|
Plain HTML | plain-html |
- |
Markdown | astro | 2.63 |
gitbook | 2.52 | |
React | Next.js | 3.43 |
Vue | nuxt | 2.15 |
Go | hugo | 3.14 |
Ruby | jekyll | 2.46 |