Build MVP website from README #338

bachand · 2025-11-22T19:08:09Z

Summary

Adds the ability to convert the README.md to a website. This productionizes #336 following positive internal feedback on the direction.

The next steps will be to set up a GitHub workflow to publish the site to GitHub Pages. We may also want to continue to polish the style.

Reasoning

A website will make the style guide more accessible. We chose to generate the website from the README so that the existing workflow for updating the style guide remains the same.

Testing

Run bundle exec rake site:serve locally and check the content at http://localhost:4000
Verify that top badges and SPM command plugin sections are filtered out of the site

Top	Code block	Footer

Please review

@airbnb/swift-styleguide-maintainers

bachand · 2025-11-22T19:39:32Z

README.md

  ]
  ```

+  </details>


I noticed that some details closing tags were missing.

bachand · 2025-11-22T19:59:00Z

Gemfile

-source 'https://rubygems.org' do
-  gem "rake", "~> 13.0.0"
-end
+source 'https://rubygems.org'


I reworked this file to address this warning from Bundler:

[DEPRECATED] This Gemfile does not include an explicit global source. Not using an explicit global source may result in a different lockfile being generated depending on the gems you have installed locally before bundler is run. Instead, define a global source in your Gemfile like this: source "https://rubygems.org".

bachand · 2025-11-22T20:57:22Z

site/src/assets/css/style.css

@@ -0,0 +1,48 @@
+body {


I relied on AI to generate this styling and it looks like a good starting point to me.

bachand · 2025-11-22T21:00:16Z

site/src/_config.yml

+markdown: kramdown
+kramdown:
+  input: GFM
+  parse_block_html: true


This was necessary for the code blocks to render correctly.

bachand · 2025-11-22T21:02:23Z

site/src/_layouts/default.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>


I decided to put files that are inputs into the site under a src/ subdirectory to avoid needing to manage excludes in the _config.yml file. In this way, only files under src/ will be used to generate the site.

bachand · 2025-11-22T22:03:09Z

This PR is ready for review, and there is also no rush. I plan to address any feedback after Thanksgiving.

calda · 2025-12-01T18:43:04Z

.github/workflows/main.yml

+        with:
+          bundler-cache: true
+      - name: Build site
+        run: bundle exec rake site:build


Is this actually deploying the site? Or just validating that it builds successfully? My guess it that it's just validating the build.

Yes, this is validating that it builds. We'll need to add a separate workflow for deployment.

calda · 2025-12-01T18:47:02Z

Rakefile

+namespace :site do
+  desc 'Prints the README content used to build the site'
+  task :filter_readme do
+    require_relative 'site/site_content'
+    puts SiteContent.new.filter_readme
+  end
+
+  desc 'Prepares index.md and syntax highlighting assets'
+  task :prepare do
+    require_relative 'site/site_content'
+    puts '📋 Generating index.md from README.md with frontmatter...'
+    SiteContent.new.write_index
+    puts '🎨 Generating syntax highlighting CSS...'
+    SiteContent.new.generate_syntax_css
+  end
+
+  desc 'Builds the static site into _site/'
+  task build: :prepare do
+    env = { 'JEKYLL_ENV' => ENV.fetch('JEKYLL_ENV', 'production') }
+    sh env, 'bundle exec jekyll build --source site/src'
+  end
+
+  desc 'Serves the site to support previewing its content during development'
+  task serve: :prepare do
+    env = { 'JEKYLL_ENV' => 'development' }
+    sh env, 'bundle exec jekyll serve --source site/src'
+  end


When would you run these commands? Do they have to be ran manually each time we make content changes?

Thanks for asking. I clarified two of the commands in #339. site:build is mostly for CI validation.

calda

Awesome!! Looks great! I had no idea you could pre-process Jekyll input markdown. Such a great idea.

Is the site built and deployed automatically by GitHub on every commit, or do we have to do it manually? My past experience with Jekyll makes me think it's deployed automatically, but I don't know how exactly GitHub would know to run our custom build code. It would be good to document exactly how the deployment works in the site/README.md once we know for sure it all works.

calda · 2025-12-01T18:54:35Z

The next steps will be to set up a GitHub workflow to publish the site to GitHub Pages.

I see, we haven't set this up yet. Handling this in a follow-up works for me. I also wouldn't mind setting up this part.

bachand · 2025-12-01T19:15:35Z

Awesome!! Looks great! I had no idea you could pre-process Jekyll input markdown. Such a great idea.

🎉 😃

The next steps will be to set up a GitHub workflow to publish the site to GitHub Pages.

I see, we haven't set this up yet. Handling this in a follow-up works for me. I also wouldn't mind setting up this part.

Yes. Thanks for taking a look @calda !

#### Summary I noticed when working on #338 that the README.md has some trailing newlines. My VS Code is set up to remove these on save. I avoided removing them in that PR to keep it focused, so I'm following up to to remove them here. I'm also clarifying a couple of the tasks that I added based on [this](#338 (comment)) feedback. #### Testing CI #### Please review @airbnb/swift-styleguide-maintainers

add site namespace to Rakefile

883b15b

bachand mentioned this pull request Nov 22, 2025

[Prototype] Site built using Jekyll for GitHub page #336

Closed

bachand commented Nov 22, 2025

View reviewed changes

README.md

]

```

</details>

Copy link

Contributor Author

bachand Nov 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I noticed that some details closing tags were missing.

bachand added 4 commits November 22, 2025 11:41

add serve task

7a9d423

Add site readme

7e33cff

add and install jekyll

44f490d

add missing details closing tags to README

55ed3a3

bachand force-pushed the mb--site-mvp branch from 4b992c2 to 55ed3a3 Compare November 22, 2025 19:41

bachand added 2 commits November 22, 2025 11:52

add main github action

6a80f35

modernize gemfile

2ae527b

bachand commented Nov 22, 2025

View reviewed changes

bachand added 2 commits November 22, 2025 12:19

add site content generator

9d2ab0c

polish

49c70c7

bachand changed the title ~~Build website from README~~ Build MVP website from README Nov 22, 2025

bachand commented Nov 22, 2025

View reviewed changes

bachand added 2 commits November 22, 2025 13:03

newline

b35f858

simplify

9fbbe2f

bachand marked this pull request as ready for review November 22, 2025 21:41

calda reviewed Dec 1, 2025

View reviewed changes

calda approved these changes Dec 1, 2025

View reviewed changes

bachand merged commit 9cafcd9 into airbnb:master Dec 1, 2025
5 checks passed

bachand deleted the mb--site-mvp branch December 1, 2025 19:00

bachand mentioned this pull request Dec 1, 2025

Small cleanups after introducing MVP site #339

Merged

calda mentioned this pull request Dec 1, 2025

Deploy site to GitHub pages #340

Merged

Build MVP website from README #338

Build MVP website from README #338

Uh oh!

Conversation

bachand commented Nov 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Reasoning

Testing

Please review

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bachand commented Nov 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

calda left a comment

Choose a reason for hiding this comment

Uh oh!

calda commented Dec 1, 2025

Uh oh!

Uh oh!

bachand commented Dec 1, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bachand commented Nov 22, 2025 •

edited

Loading

bachand commented Nov 22, 2025 •

edited

Loading