dark-dungeons-theme 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d6248f617a2624c1bebf746968439123f0308985ba5dfbea0f390c40b97e1ed
+  data.tar.gz: cf6ffc5d0c0689e2f6653705d5f8055bd230dc664957b6844b839c19c4634a2c
+SHA512:
+  metadata.gz: ea7cb93c94522d8b3d71ca59327d27e851a82919ee6199b82afecf738db191be22b66fde3e5ce514759fdc8250026450dd418d1d99a7b492d0b174894b79cda8
+  data.tar.gz: 52e19b30267a78dd7adbda0f143117bf862478bd0456158e1a850ca01af32b8fb83504325f40e940bf2d5b11b04958391c712bb2f9a4afc2ba7ec5767dd143a1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dark Dungeons theme contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,91 @@
+# Dark Dungeons Theme
+
+A visual overlay gem for [Just the Docs](https://github.com/just-the-docs/just-the-docs). It applies the Dark Dungeons look (dark palette, typography, links, and callout styling) without changing your site title, favicon, navigation content, or pages.
+
+Inspired by the [Designing Dungeons Course](https://dungeons.hismajestytheworm.games/).
+
+Works with sites created from [just-the-docs-template](https://github.com/just-the-docs/just-the-docs-template).
+
+## Usage
+
+In your site's `Gemfile`:
+
+```ruby
+gem "just-the-docs", "0.12.0"
+gem "dark-dungeons-theme", path: "../designing-dungeons-theme"
+# or from git:
+# gem "dark-dungeons-theme", github: "sunflowermans/designing-dungeons-theme"
+```
+
+In `_config.yml`, keep Just the Docs as the theme and load this gem as a plugin:
+
+```yaml
+theme: just-the-docs
+
+plugins:
+  - dark-dungeons-theme
+```
+
+Then:
+
+```sh
+bundle install
+bundle exec jekyll serve
+```
+
+Loading the plugin sets `color_scheme: dark-dungeons`, defaults
+`callouts_level` to `loud`, and registers a common callout set. Your existing
+pages and site metadata stay the same.
+
+### Callouts
+
+These are available without extra config:
+
+| Class | Color | Title |
+| --- | --- | --- |
+| `highlight` | yellow | — |
+| `note` | purple | — |
+| `important` | red | Important |
+| `warning` | red | Warning |
+| `new` | green | New |
+
+```markdown
+{: .note }
+A short note for the reader.
+```
+
+Override or add callouts in `_config.yml` (your entries win on name clashes):
+
+```yaml
+callouts:
+  important:
+    title: Critical
+    color: red
+  tip:
+    title: Tip
+    color: blue
+```
+
+### Opt out
+
+```yaml
+dark_dungeons_theme: false
+```
+
+## What this gem changes
+
+- Dark Dungeons color scheme
+- Heading letter-spacing and `h2` underline
+- Link weight and hover color
+- Sidebar link weight
+- Soft tinted callout backgrounds for the default callout set
+- TOC label hiding in the markdown TOC
+
+## What this gem does not include
+
+- Favicons or logos
+- Author-specific callouts (e.g. course sidebars) or icons
+
+## License
+
+MIT

data/_includes/css/callouts.scss.liquid

@@ -0,0 +1,92 @@
+{%- comment -%}
+  Dark Dungeons callout visuals for Just the Docs.
+  Soft tinted backgrounds (instead of bordered boxes) and loud-mode accent hues.
+{%- endcomment -%}
+
+{%- assign callout_background_hue = "000" -%}
+{%- assign callout_color_hue = "300" -%}
+{%- if site.callouts_level == "loud" or include.color_scheme == "dark" and site.callouts_level != "quiet" -%}
+  {%- assign callout_background_hue = "300" -%}
+  {%- assign callout_color_hue = "000" -%}
+{%- endif -%}
+
+div.opaque {
+  background-color: $body-background-color;
+}
+
+{%- for callout in site.callouts %}
+
+{%- assign callout_opacity = callout[1].opacity | default: site.callouts_opacity | default: 0.2 -%}
+
+p.{{ callout[0] }}, blockquote.{{ callout[0] }} {
+    background: rgba(${{ callout[1].color }}-{{ callout_background_hue }}, {{ callout_opacity }});
+    border-left: $border-radius solid ${{ callout[1].color }}-{{ callout_color_hue }};
+    border-radius: $border-radius;
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+    padding: .8rem;
+    {% if callout[1].title %}
+    &::before {
+        color: ${{ callout[1].color }}-{{ callout_color_hue }};
+        content: "{{ callout[1].title }}";
+        display: block;
+        font-weight: bold;
+        text-transform: uppercase;
+        font-size: .75em;
+        padding-bottom: .125rem;
+    }
+    {% endif %}
+    > .{{ callout[0] }}-title {
+      color: ${{ callout[1].color }}-{{ callout_color_hue }};
+      display: block;
+      font-weight: bold;
+      text-transform: uppercase;
+      font-size: .75em;
+      padding-bottom: .125rem;
+    }
+}
+
+p.{{ callout[0] }}-title, blockquote.{{ callout[0] }}-title {
+    background: rgba(${{ callout[1].color }}-{{ callout_background_hue }}, {{ callout_opacity }});
+    border-left: $border-radius solid ${{ callout[1].color }}-{{ callout_color_hue }};
+    border-radius: $border-radius;
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+    padding: .8rem;
+    > p:first-child {
+      margin-top: 0;
+      margin-bottom: 0;
+      color: ${{ callout[1].color }}-{{ callout_color_hue }};
+      display: block;
+      font-weight: bold;
+      text-transform: uppercase;
+      font-size: .75em;
+      padding-bottom: .125rem;
+    }
+}
+
+blockquote.{{ callout[0] }} {
+  margin-left: 0;
+  margin-right: 0;
+
+  > p:first-child {
+    margin-top: 0;
+  }
+
+  > p:last-child {
+    margin-bottom: 0;
+  }
+}
+
+blockquote.{{ callout[0] }}-title {
+  margin-left: 0;
+  margin-right: 0;
+
+  > p:nth-child(2) {
+    margin-top: 0;
+  }
+
+  > p:last-child {
+    margin-bottom: 0;
+  }
+}
+
+{% endfor -%}

data/_sass/color_schemes/dark-dungeons.scss

@@ -0,0 +1,26 @@
+// Dark Dungeons visual scheme for Just the Docs.
+// Based on the dark scheme with contrast-tuned colors and typography.
+@import "./color_schemes/dark";
+
+$body-text-color: #b7b0b9;
+// Keep dark scheme $body-heading-color ($grey-lt-000 / #f5f6fa).
+// Original custom-dark set color:#fff on headings, but base.scss overrides
+// that with $body-heading-color — matching that effective result.
+
+// Sidebar and general links — lighter for dark backgrounds
+$nav-child-link-color: $grey-lt-000;
+$link-color: $grey-lt-000;
+
+// Callout accents — higher contrast on dark surfaces
+$blue-000: #80b3ff;
+$green-000: #98e6a1;
+$yellow-000: #ffe380;
+$red-000: #ff9e9e;
+$purple-000: #d8b3ff;
+
+// Callout backgrounds — darker, still distinguishable
+$blue-300: #1a365d;
+$green-300: #1a4731;
+$yellow-300: #644c04;
+$red-300: #dd2e2e;
+$purple-300: #432160;

data/assets/css/dark-dungeons-theme.css

@@ -0,0 +1,50 @@
+/* Dark Dungeons visual overrides for Just the Docs.
+   Loaded after the theme stylesheet.
+
+   Heading font-weight/color from the original custom-dark scheme are
+   intentionally omitted: in Dark Dungeons those rules compile early
+   (via the color scheme) and lose to Just the Docs typography/base, so
+   h1 stays font-weight 300 / $body-heading-color. Re-applying them here
+   would make {: .fs-9 } heroes bold/white instead of matching the original. */
+
+.callout,
+.callout p {
+  color: #e6e1e8;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  letter-spacing: -0.02em;
+}
+
+h2 {
+  border-bottom: 1px solid #44434d;
+  padding-bottom: 0.3em;
+}
+
+.site-title {
+  font-size: 1.35rem !important;
+  white-space: nowrap;
+}
+
+a {
+  font-weight: 500;
+  text-decoration: none;
+}
+
+a:hover {
+  color: #b8f7ff;
+  text-decoration: underline;
+}
+
+.nav-list .nav-list-item .nav-list-link {
+  font-weight: 500;
+}
+
+#markdown-toc .label {
+  display: none;
+}

data/dark-dungeons-theme.gemspec

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "lib/dark_dungeons_theme/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "dark-dungeons-theme"
+  spec.version       = DarkDungeonsTheme::VERSION
+  spec.authors       = ["Dark Dungeons"]
+  spec.email         = []
+
+  spec.summary       = "Visual theme overlay for Just the Docs (Dark Dungeons)"
+  spec.description   = "Applies the Dark Dungeons color scheme, typography, and callout " \
+                       "styling to a Just the Docs site without changing content or branding."
+  spec.homepage      = "https://github.com/sunflowermans/dark-dungeons-theme"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage
+  }
+
+  spec.files = Dir.chdir(__dir__) do
+    tracked = `git ls-files -z`.split("\x0")
+    tracked = Dir[
+      "lib/**/*",
+      "_sass/**/*",
+      "_includes/**/*",
+      "assets/**/*",
+      "LICENSE*",
+      "README*",
+      "*.gemspec"
+    ] if tracked.empty?
+
+    tracked.reject do |f|
+      f.start_with?(".", "test/", "spec/", "features/") ||
+        File.directory?(f) ||
+        %w[Gemfile Gemfile.lock].include?(f)
+    end
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "jekyll", ">= 3.8.5", "< 5.0"
+  spec.add_development_dependency "bundler", ">= 2.3"
+  spec.add_development_dependency "rake", ">= 13.0"
+end

data/lib/dark-dungeons-theme.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "jekyll"
+
+require_relative "dark_dungeons_theme/version"
+require_relative "dark_dungeons_theme/hooks"

data/lib/dark_dungeons_theme/hooks.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module DarkDungeonsTheme
+  # Common Just the Docs callouts, styled by this gem's palette/backgrounds.
+  # Site `_config.yml` entries override or extend these defaults.
+  DEFAULT_CALLOUTS = {
+    "highlight" => { "color" => "yellow" },
+    "note" => { "color" => "purple" },
+    "important" => { "title" => "Important", "color" => "red" },
+    "warning" => { "title" => "Warning", "color" => "red" },
+    "new" => { "title" => "New", "color" => "green" }
+  }.freeze
+
+  module Paths
+    module_function
+
+    def root
+      File.expand_path("../..", __dir__)
+    end
+
+    def sass_dir
+      File.join(root, "_sass")
+    end
+
+    def includes_dir
+      File.join(root, "_includes")
+    end
+
+    def assets_dir
+      File.join(root, "assets")
+    end
+  end
+
+  class << self
+    def enabled?(site)
+      site.config["dark_dungeons_theme"] != false
+    end
+
+    def apply_config!(site)
+      return unless enabled?(site)
+
+      site.config["color_scheme"] = "dark-dungeons"
+      site.config["callouts_level"] ||= "loud"
+      site.config["callouts"] = DEFAULT_CALLOUTS.merge(site.config["callouts"] || {})
+    end
+
+    def configure_sass_load_paths!(site)
+      return unless enabled?(site)
+
+      site.config["sass"] ||= {}
+      load_paths = Array(site.config["sass"]["load_paths"]).dup
+      load_paths << Paths.sass_dir unless load_paths.include?(Paths.sass_dir)
+      site.config["sass"]["load_paths"] = load_paths
+    end
+
+    def configure_includes_load_paths!(site)
+      return unless enabled?(site)
+
+      includes_paths = site.includes_load_paths
+      return if includes_paths.include?(Paths.includes_dir)
+
+      # Prefer site overrides, then this gem, then the active theme.
+      insert_at = [includes_paths.length, 1].min
+      includes_paths.insert(insert_at, Paths.includes_dir)
+    end
+
+    def register_assets!(site)
+      return unless enabled?(site)
+
+      css_name = "dark-dungeons-theme.css"
+      already_registered = site.static_files.any? do |file|
+        file.relative_path == "/assets/css/#{css_name}"
+      end
+      return if already_registered
+
+      site.static_files << Jekyll::StaticFile.new(
+        site,
+        Paths.root,
+        "assets/css",
+        css_name
+      )
+    end
+
+    def html_output?(doc)
+      return false if doc.output.nil? || doc.output.empty?
+      return true if doc.respond_to?(:output_ext) && doc.output_ext == ".html"
+
+      doc.output.include?("</head>")
+    end
+
+    def inject_stylesheet!(doc)
+      return unless html_output?(doc)
+      return unless doc.output.include?("</head>")
+      return if doc.output.include?("dark-dungeons-theme.css")
+
+      baseurl = doc.site.config["baseurl"].to_s.chomp("/")
+      href = "#{baseurl}/assets/css/dark-dungeons-theme.css"
+      tag = %(<link rel="stylesheet" href="#{href}">\n)
+      doc.output = doc.output.sub("</head>", "#{tag}</head>")
+    end
+  end
+end
+
+Jekyll::Hooks.register :site, :after_init do |site|
+  DarkDungeonsTheme.apply_config!(site)
+  DarkDungeonsTheme.configure_sass_load_paths!(site)
+end
+
+Jekyll::Hooks.register :site, :post_read do |site|
+  DarkDungeonsTheme.configure_includes_load_paths!(site)
+  DarkDungeonsTheme.register_assets!(site)
+end
+
+%i[pages documents].each do |owner|
+  Jekyll::Hooks.register owner, :post_render do |doc|
+    next unless DarkDungeonsTheme.enabled?(doc.site)
+
+    DarkDungeonsTheme.inject_stylesheet!(doc)
+  end
+end

data/lib/dark_dungeons_theme/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DarkDungeonsTheme
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: dark-dungeons-theme
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dark Dungeons
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.8.5
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.8.5
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Applies the Dark Dungeons color scheme, typography, and callout styling
+  to a Just the Docs site without changing content or branding.
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- _includes/css/callouts.scss.liquid
+- _sass/color_schemes/dark-dungeons.scss
+- assets/css/dark-dungeons-theme.css
+- dark-dungeons-theme.gemspec
+- lib/dark-dungeons-theme.rb
+- lib/dark_dungeons_theme/hooks.rb
+- lib/dark_dungeons_theme/version.rb
+homepage: https://github.com/sunflowermans/dark-dungeons-theme
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sunflowermans/dark-dungeons-theme
+  source_code_uri: https://github.com/sunflowermans/dark-dungeons-theme
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Visual theme overlay for Just the Docs (Dark Dungeons)
+test_files: []