Merge branch 'main' into add-chromatic

This PR moves over the changes from https://github.com/just-the-docs/just-the-docs/pull/1112, namely making the `.gitignore` more descriptive and bringing it to parity with the recommendations from Jekyll.

---------

Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>

.babelrc.json

@@ -0,0 +1,15 @@
+{
+  "sourceType": "unambiguous",
+  "presets": [
+    [
+      "@babel/preset-env",
+      {
+        "targets": {
+          "chrome": 100
+        }
+      }
+    ],
+    "@babel/preset-typescript"
+  ],
+  "plugins": []
+}

.github/workflows/chromatic.yml

@@ -0,0 +1,51 @@
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+name: 'Chromatic'
+
+jobs:
+  chromatic:
+    name: "Chromatic"
+    strategy:
+      matrix:
+        jekyll-version: [4.3]
+        os: [ ubuntu-latest ]
+        ruby-version: [3.1]
+        node-version: [18.x]
+    runs-on: ${{ matrix.os }}
+    steps:
+
+    # Ruby setup
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+    - name: Setup Ruby ${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: false
+    - name: Bundle Install
+      run: bundle install
+    - name: Install Jekyll ${{ matrix.jekyll-version }}
+      run: gem install jekyll -v ${{ matrix.jekyll-version }}
+    - name: Init Search
+      run: bundle exec rake search:init
+    - name: Build Site
+      run: bundle exec jekyll build
+
+    # Node setup
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: npm install
+    - run: npm run build-storybook
+    - name: Publish to Chromatic
+      uses: chromaui/action@v1
+      env:
+        CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
       matrix:
         jekyll-version: [3.9, 4.3]
         os: [ ubuntu-latest, macos-latest, windows-latest ]
-        ruby-version: [2.7, 3.1]
+        ruby-version: ["3.0", "3.1", "3.2"]
     runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v3
@@ -46,7 +46,7 @@ jobs:
     - name: Setup Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.1'
+        ruby-version: "3.2"
         bundler-cache: false
     - name: Bundle Install
       run: bundle install
@@ -62,7 +62,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: [3.1]
+        ruby-version: ["3.2"]
     runs-on: ubuntu-latest
 
     steps:
@@ -87,7 +87,7 @@ jobs:
           root: _site
           blacklist: line-numbers
       - name: Test with html-proofer
-        run: bundle exec htmlproofer _site --ignore-urls "/github.com/"
+        run: bundle exec htmlproofer _site --ignore-urls "/github.com/,/web.archive.org/"
         env:
           NOKOGIRI_USE_SYSTEM_LIBRARIES: true
 

.github/workflows/deploy.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.1' # Not needed with a .ruby-version file
+          ruby-version: "3.2"
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
           cache-version: 0 # Increment this number if you need to re-download cached gems
       - name: Setup Pages

.github/workflows/publish-gem.yml

@@ -10,10 +10,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
-    - name: Set up Ruby 3.1
-      uses: actions/setup-ruby@v1
+    - name: Setup Ruby 3.2
+      uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 3.1
+        ruby-version: "3.2"
 
     - name: Publish to GPR
       run: |

.gitignore

@@ -1,9 +1,33 @@
+# Not sure what a .gitignore is?
+# See: https://git-scm.com/docs/gitignore
+
+# The first files are directly copied from Jekyll's first-party docs on `.gitignore` files:
+# https://jekyllrb.com/tutorials/using-jekyll-with-bundler/#commit-to-source-control
+
+# Ignore the default location of the built site, and caches and metadata generated by Jekyll
+_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata
+
+# Ignore folders generated by Bundler
+.bundle/
+vendor/
+
+# These next files are used by Just the Docs developers. They are not necessary for end users of the theme, only developers.
+
+# We use Stylelint and Prettier, JavaScript tools, to lint and format our own code,
+# We use Node.js as our runtime, so we ignore node_modules
+node_modules
+
+# We also use Storybook to test regressions in changes; we ignore the build output.
+storybook-static
+
+# .DS_Store is a macOS-only metadata file about directories. Convention is to not commit them.
+# See: https://en.wikipedia.org/wiki/.DS_Store
+.DS_Store
+
+# These are legacy globs that typically target Ruby theme developers. We may change these at a later date.
 *.gem
 .bundle
 .ruby-version
-.jekyll-cache
-.sass-cache
-_site
-Gemfile.lock
-node_modules
-.DS_Store

.storybook/main.js

@@ -0,0 +1,17 @@
+/** @type { import('@storybook/html-webpack5').StorybookConfig } */
+const config = {
+  stories: ["../stories/**/*.mdx", "../stories/**/*.stories.@(js|jsx|ts|tsx)"],
+  addons: [
+    "@storybook/addon-links",
+    "@storybook/addon-essentials",
+    "@storybook/addon-interactions",
+  ],
+  framework: {
+    name: "@storybook/html-webpack5",
+    options: {},
+  },
+  docs: {
+    autodocs: "tag",
+  },
+}
+export default config

.storybook/preview.js

@@ -0,0 +1,14 @@
+/** @type { import('@storybook/html').Preview } */
+const preview = {
+  parameters: {
+    actions: { argTypesRegex: "^on[A-Z].*" },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/,
+      },
+    },
+  },
+}
+
+export default preview

CHANGELOG.md

@@ -17,7 +17,25 @@ This website is built from the `HEAD` of the `main` branch of the theme reposito
 
 Code changes to `main` that are *not* in the latest release:
 
-- N/A
+- Fixed: Windows emoji font fallback by [@flanakin] in [#1337]
+
+[#1337]: https://github.com/just-the-docs/just-the-docs/pull/1337
+
+### New Contributors
+
+- [@flanakin] made their first contribution in [#1337]
+
+[@flanakin]: https://github.com/flanakin
+
+## Release v0.6.1
+
+Hi all, this is a small patch release that only includes one change: resolving a bug introduced in 0.6.0 that causes a JS error for pages excluded from navigation.
+
+### Bugfixes
+
+- Fixed: JS error for pages excluded from navigation by [@pdmosses] in [#1332]
+
+[#1332]: https://github.com/just-the-docs/just-the-docs/pull/1332
 
 ## Release v0.6.0
 

Gemfile

@@ -5,6 +5,4 @@ gem "jekyll-github-metadata", ">= 2.15"
 
 gem "jekyll-include-cache", group: :jekyll_plugins
 
-gem "webrick", "~> 1.7"
-
 gem "html-proofer", "~> 5.0", :group => :development

Gemfile.lock

@@ -0,0 +1,150 @@
+PATH
+  remote: .
+  specs:
+    just-the-docs (0.6.1)
+      jekyll (>= 3.8.5)
+      jekyll-include-cache
+      jekyll-seo-tag (>= 2.0)
+      rake (>= 12.3.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    Ascii85 (1.1.0)
+    addressable (2.8.4)
+      public_suffix (>= 2.0.2, < 6.0)
+    afm (0.2.2)
+    async (2.6.3)
+      console (~> 1.10)
+      fiber-annotation
+      io-event (~> 1.1)
+      timers (~> 4.1)
+    colorator (1.1.0)
+    concurrent-ruby (1.2.2)
+    console (1.23.2)
+      fiber-annotation
+      fiber-local
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    ethon (0.16.0)
+      ffi (>= 1.15.0)
+    eventmachine (1.2.7)
+    faraday (2.7.10)
+      faraday-net_http (>= 2.0, < 3.1)
+      ruby2_keywords (>= 0.0.4)
+    faraday-net_http (3.0.2)
+    ffi (1.15.5)
+    fiber-annotation (0.2.0)
+    fiber-local (1.0.0)
+    forwardable-extended (2.6.0)
+    google-protobuf (3.23.4-arm64-darwin)
+    google-protobuf (3.23.4-x86_64-linux)
+    hashery (2.1.2)
+    html-proofer (5.0.8)
+      addressable (~> 2.3)
+      async (~> 2.1)
+      nokogiri (~> 1.13)
+      pdf-reader (~> 2.11)
+      rainbow (~> 3.0)
+      typhoeus (~> 1.3)
+      yell (~> 2.0)
+      zeitwerk (~> 2.5)
+    http_parser.rb (0.8.0)
+    i18n (1.14.1)
+      concurrent-ruby (~> 1.0)
+    io-event (1.2.3)
+    jekyll (4.3.2)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (>= 0.3.6, < 0.5)
+      pathutil (~> 0.9)
+      rouge (>= 3.0, < 5.0)
+      safe_yaml (~> 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-github-metadata (2.16.0)
+      jekyll (>= 3.4, < 5.0)
+      octokit (>= 4, < 7, != 4.4.0)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-sass-converter (3.0.0)
+      sass-embedded (~> 1.54)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.4)
+    listen (3.8.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    nokogiri (1.15.4-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.15.4-x86_64-linux)
+      racc (~> 1.4)
+    octokit (6.1.1)
+      faraday (>= 1, < 3)
+      sawyer (~> 0.9)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    pdf-reader (2.11.0)
+      Ascii85 (~> 1.0)
+      afm (~> 0.2.1)
+      hashery (~> 2.0)
+      ruby-rc4
+      ttfunk
+    public_suffix (5.0.3)
+    racc (1.7.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.6)
+    rouge (4.1.2)
+    ruby-rc4 (0.1.5)
+    ruby2_keywords (0.0.5)
+    safe_yaml (1.0.5)
+    sass-embedded (1.64.1-arm64-darwin)
+      google-protobuf (~> 3.23)
+    sass-embedded (1.64.1-x86_64-linux-gnu)
+      google-protobuf (~> 3.23)
+    sawyer (0.9.2)
+      addressable (>= 2.3.5)
+      faraday (>= 0.17.3, < 3)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    timers (4.3.5)
+    ttfunk (1.7.0)
+    typhoeus (1.4.0)
+      ethon (>= 0.9.0)
+    unicode-display_width (2.4.2)
+    webrick (1.8.1)
+    yell (2.2.2)
+    zeitwerk (2.6.11)
+
+PLATFORMS
+  arm64-darwin
+  x86_64-linux
+
+DEPENDENCIES
+  bundler (>= 2.3.5)
+  html-proofer (~> 5.0)
+  jekyll-github-metadata (>= 2.15)
+  jekyll-include-cache
+  just-the-docs!
+
+BUNDLED WITH
+   2.4.13

_config.yml

@@ -48,6 +48,7 @@ exclude:
    - Dockerfile
  # theme test code
    - fixtures/
+   - stories/
 
 # Set a path/url to a logo that will be displayed instead of the title
 #logo: "/assets/images/just-the-docs.png"

_sass/buttons.scss

@@ -105,7 +105,7 @@
 }
 
 .btn-purple {
-  @include btn-color($white, $purple-100);
+  @include btn-color($white, $purple-300);
 }
 
 .btn-blue {

_sass/support/_variables.scss

@@ -2,7 +2,7 @@
 
 // prettier-ignore
 $body-font-family: system-ui, -apple-system, blinkmacsystemfont, "Segoe UI",
-  roboto, "Helvetica Neue", arial, sans-serif !default;
+  roboto, "Helvetica Neue", arial, sans-serif, "Segoe UI Emoji" !default;
 $mono-font-family: "SFMono-Regular", menlo, consolas, monospace !default;
 $root-font-size: 16px !default; // DEPRECATED: previously base font-size for rems
 $body-line-height: 1.4 !default;

assets/js/just-the-docs.js

@@ -76,7 +76,9 @@ function initNav() {
 // The page-specific stylesheet is assumed to have index 1 in the list of stylesheets.
 
 function disableHeadStyleSheet() {
+  if (document.styleSheets[1]) {
     document.styleSheets[1].disabled = true;
+  }
 }
 
 {%- if site.search_enabled != false %}

docs/ui-components/typography.md

@@ -21,7 +21,7 @@ nav_order: 1
 By default, Just the Docs uses a native system font stack for sans-serif fonts:
 
 ```scss
-system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif
+system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Segoe UI Emoji"
 ```
 
 ABCDEFGHIJKLMNOPQRSTUVWXYZ

just-the-docs.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "just-the-docs"
-  spec.version       = "0.6.0"
+  spec.version       = "0.6.1"
   spec.authors       = ["Patrick Marsceill", "Matthew Wang"]
   spec.email         = ["patrick.marsceill@gmail.com", "matt@matthewwang.me"]
 

package.json

@@ -1,14 +1,32 @@
 {
   "name": "just-the-docs",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "A modern Jekyll theme for documentation",
-  "repository": "just-the-docs/just-the-docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/just-the-docs/just-the-docs.git"
+  },
   "license": "MIT",
-  "bugs": "https://github.com/just-the-docs/just-the-docs/issues",
+  "bugs": {
+    "url": "https://github.com/just-the-docs/just-the-docs/issues"
+  },
   "devDependencies": {
+    "@babel/preset-env": "^7.21.4",
+    "@babel/preset-typescript": "^7.21.4",
+    "@storybook/addon-essentials": "^7.0.7",
+    "@storybook/addon-interactions": "^7.0.7",
+    "@storybook/addon-links": "^7.0.7",
+    "@storybook/blocks": "^7.0.7",
+    "@storybook/html": "^7.0.7",
+    "@storybook/html-webpack5": "^7.0.7",
+    "@storybook/testing-library": "^0.0.14-next.2",
+    "chromatic": "^6.17.3",
     "npm-run-all": "^4.1.5",
-    "prettier": "^3.0.2",
-    "stylelint": "^15.10.2",
+    "prettier": "^3.0.3",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "storybook": "^7.0.7",
+    "stylelint": "^15.10.3",
     "stylelint-config-standard-scss": "^10.0.0"
   },
   "scripts": {
@@ -16,7 +34,10 @@
     "lint:css": "stylelint '**/*.scss'",
     "lint:formatting": "prettier --check '**/*.{scss,js,json}'",
     "format": "prettier --write '**/*.{scss,js,json}'",
-    "test": "npm run lint"
+    "test": "npm run lint",
+    "storybook": "bundle exec jekyll build && storybook dev -p 6006",
+    "build-storybook": "bundle exec jekyll build && storybook build",
+    "chromatic": "npx chromatic --project-token=9355f489c51b -d storybook-static"
   },
   "stylelint": {
     "ignoreFiles": [
@@ -43,5 +64,7 @@
     "singleQuote": false,
     "tabWidth": 2,
     "trailingComma": "es5"
-  }
+  },
+  "homepage": "https://just-the-docs.com",
+  "_id": "just-the-docs@0.5.0"
 }

stories/Introduction.mdx

@@ -0,0 +1,7 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Example/Introduction" />
+
+# Storybook for Just the Docs
+
+A WIP [Storybook](https://storybook.js.org/) for Just the Docs.

stories/ui-components/Button.js

@@ -0,0 +1,11 @@
+import "../../_site/assets/css/just-the-docs-default.css"
+
+export const createButton = ({ variant = "default", label, size = "4" }) => {
+  const btn = document.createElement("button")
+  btn.type = "button"
+  btn.innerText = label
+
+  btn.className = ["btn", `btn-${variant}`, `fs-${size}`].join(" ")
+
+  return btn
+}

stories/ui-components/Button.stories.js

@@ -0,0 +1,68 @@
+import { createButton } from "./Button"
+
+export default {
+  title: "UI Components/Button",
+  tags: ["autodocs"],
+  render: ({ label, ...args }) => {
+    return createButton({ label, ...args })
+  },
+  argTypes: {
+    label: { control: "text" },
+    size: {
+      control: { type: "select" },
+      options: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    },
+    variant: {
+      control: { type: "select" },
+      options: ["default", "primary", "purple", "blue", "green", "outline"],
+    },
+  },
+}
+
+export const Default = {
+  args: {
+    variant: "default",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Primary = {
+  args: {
+    variant: "primary",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Purple = {
+  args: {
+    variant: "purple",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Blue = {
+  args: {
+    variant: "blue",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Green = {
+  args: {
+    variant: "green",
+    label: "Button",
+    size: 4,
+  },
+}
+
+export const Outline = {
+  args: {
+    variant: "outline",
+    label: "Button",
+    size: 4,
+  },
+}

stories/ui-components/Label.js

@@ -0,0 +1,10 @@
+import "../../_site/assets/css/just-the-docs-default.css"
+
+export const createLabel = ({ variant = "default", label, size = "4" }) => {
+  const btn = document.createElement("span")
+  btn.innerText = label
+
+  btn.className = ["label", `label-${variant}`, `fs-${size}`].join(" ")
+
+  return btn
+}

stories/ui-components/Label.stories.js

@@ -0,0 +1,68 @@
+import { createLabel } from "./Label"
+
+export default {
+  title: "UI Components/Label",
+  tags: ["autodocs"],
+  render: ({ label, ...args }) => {
+    return createLabel({ label, ...args })
+  },
+  argTypes: {
+    label: { control: "text" },
+    size: {
+      control: { type: "select" },
+      options: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    },
+    variant: {
+      control: { type: "select" },
+      options: ["default", "purple", "blue", "green", "red", "yellow"],
+    },
+  },
+}
+
+export const Default = {
+  args: {
+    variant: "default",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Purple = {
+  args: {
+    variant: "purple",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Blue = {
+  args: {
+    variant: "blue",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Green = {
+  args: {
+    variant: "green",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Red = {
+  args: {
+    variant: "red",
+    label: "Label",
+    size: 4,
+  },
+}
+
+export const Yellow = {
+  args: {
+    variant: "yellow",
+    label: "Label",
+    size: 4,
+  },
+}