From 3ca57e3b0d2091c16283e4336d96996a989217c0 Mon Sep 17 00:00:00 2001
From: Alyssa Ross <hi@alyssa.is>
Date: Tue, 12 Jul 2022 22:15:05 +0000
Subject: [PATCH] Minor style fixes for jekyll-asciidoc (#829)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

I have a site whose content is written in AsciiDoc, using the [jekyll-asciidoc][] plugin.

Just the Docs works great, but there are just two minor styling glitches I've noticed:

The first is that Just the Docs' CSS doesn't understand the code block markup jekyll-asciidoc produces.  It's not too different though, so it's very easily fixed.

The second is that jekyll-asciidoc generates `div.sect(𝑛 − 1)` elements around headings of type `h𝑛`, that enclose all the heading and all the content after it until the next heading of greater or equal rank.

This means that headings are _always_ first children in AsciiDoc output, which meant the wrong margins were applied to most headings. To fix this, we need to only reduce the margin of first-child headings nested directly below the .main-content element, and headings nested directly below AsciiDoc `.sect𝑛` elements that are themselves first children.

With these two small changes, my site looks perfect, and the styles look exactly the same as on Just the Docs' own documentation.

[jekyll-asciidoc]: https://github.com/asciidoctor/jekyll-asciidoc
---
 _sass/base.scss       |  5 +++--
 _sass/code.scss       |  7 ++++++-
 _sass/content.scss    | 26 +++++++++++++++++++-------
 _sass/typography.scss |  5 +++--
 4 files changed, 31 insertions(+), 12 deletions(-)

diff --git a/_sass/base.scss b/_sass/base.scss
index c3b66987..4e7be5da 100644
--- a/_sass/base.scss
+++ b/_sass/base.scss
@@ -1,7 +1,7 @@
 //
 // Base element style overrides
 //
-// stylelint-disable selector-no-type, selector-max-type
+// stylelint-disable selector-no-type, selector-max-type, selector-max-specificity, selector-max-id
 
 * {
   box-sizing: border-box;
@@ -45,7 +45,8 @@ h2,
 h3,
 h4,
 h5,
-h6 {
+h6,
+#toctitle {
   margin-top: 0;
   margin-bottom: 1em;
   font-weight: 500;
diff --git a/_sass/code.scss b/_sass/code.scss
index 684a7646..a479c702 100644
--- a/_sass/code.scss
+++ b/_sass/code.scss
@@ -38,6 +38,9 @@ a:visited code {
 //   > td.gutter.gl > pre.lineno
 //   | td.code > pre
 //
+// ----...---- (AsciiDoc)
+//   div.listingblock > div.content > pre.rouge.highlight
+//
 // fix_linenos removes the outermost pre when it encloses table.rouge-table
 //
 // See docs/index-test.md for some tests.
@@ -46,7 +49,8 @@ a:visited code {
 // Kramdown line_numbers = true: fences have a wider gutter than with Liquid?
 
 // ```[LANG]...```
-div.highlighter-rouge {
+div.highlighter-rouge,
+div.listingblock {
   padding: $sp-3;
   margin-top: 0;
   margin-bottom: $sp-3;
@@ -123,6 +127,7 @@ figure.highlight {
   border-radius: $border-radius;
 
   + .highlighter-rouge,
+  + .sectionbody .listingblock,
   + figure.highlight {
     position: relative;
     margin-top: -$sp-4;
diff --git a/_sass/content.scss b/_sass/content.scss
index b28a97ae..e2ed9178 100644
--- a/_sass/content.scss
+++ b/_sass/content.scss
@@ -3,7 +3,7 @@
 //
 // Styles for rendered markdown in the .main-content container
 //
-// stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type
+// stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type, selector-max-specificity, selector-max-id
 
 .main-content {
   line-height: $content-line-height;
@@ -204,19 +204,17 @@
   h3,
   h4,
   h5,
-  h6 {
+  h6,
+  #toctitle {
     position: relative;
     margin-top: 1.5em;
     margin-bottom: 0.25em;
 
-    &:first-child {
-      margin-top: $sp-2;
-    }
-
     + table,
     + .table-wrapper,
     + .code-example,
-    + .highlighter-rouge {
+    + .highlighter-rouge,
+    + .sectionbody .listingblock {
       margin-top: 1em;
     }
 
@@ -224,4 +222,18 @@
       margin-top: 0;
     }
   }
+
+  > h1:first-child,
+  > h2:first-child,
+  > h3:first-child,
+  > h4:first-child,
+  > h5:first-child,
+  > h6:first-child,
+  > .sect1:first-child > h2,
+  > .sect2:first-child > h3,
+  > .sect3:first-child > h4,
+  > .sect4:first-child > h5,
+  > .sect5:first-child > h6 {
+    margin-top: $sp-2;
+  }
 }
diff --git a/_sass/typography.scss b/_sass/typography.scss
index 103d2579..101c66a3 100644
--- a/_sass/typography.scss
+++ b/_sass/typography.scss
@@ -1,7 +1,7 @@
 //
 // Typography
 //
-// stylelint-disable primer/selector-no-utility, primer/no-override, selector-no-type, selector-max-type
+// stylelint-disable primer/selector-no-utility, primer/no-override, selector-no-type, selector-max-type, selector-max-specificity, selector-max-id
 
 h1,
 .text-alpha {
@@ -10,7 +10,8 @@ h1,
 }
 
 h2,
-.text-beta {
+.text-beta,
+#toctitle {
   @include fs-6;
 }
 
-- 
GitLab