support filename attribute for attaching a file name header to code blocks

Author: jjallaire

news/changelog-1.1.md

@@ -22,6 +22,10 @@
 
 - Use 'Appendix' as prefix for references to chapters in appendix
 
+## Code Blocks
+
+- Support `filename` attribute for attaching a file name header to code blocks
+
 ## OJS
 
 - Better handle OJS code blocks that begin with empty lines

src/command/render/filters.ts

@@ -610,6 +610,9 @@ function pdfEngine(options: PandocOptions): string {
   return pdfEngine;
 }
 
+const kQuartoExtOrganization = "quarto-ext";
+const kQuartoExtBuiltIn = ["code-filename"];
+
 function resolveFilterExtension(
   options: PandocOptions,
   filters: QuartoFilter[],
@@ -623,7 +626,7 @@ function resolveFilterExtension(
       typeof (filter) === "string" &&
       !existsSync(filter)
     ) {
-      const extensions = options.extension?.find(
+      let extensions = options.extension?.find(
         filter,
         options.source,
         "filters",
@@ -646,6 +649,17 @@ function resolveFilterExtension(
           );
         }
 
+        // we periodically build in features that were formerly available from
+        // the quarto-ext org. filter them out here (that allows them to remain
+        // referenced in the yaml so we don't break code in the wild)
+        extensions = extensions?.filter((ext) => {
+          return ext.id.organization !== kQuartoExtOrganization &&
+            !kQuartoExtBuiltIn.includes(ext.id.name);
+        });
+        if (extensions.length === 0) {
+          return [];
+        }
+
         const filters = extensions[0].contributes.filters;
         if (filters) {
           return filters;

src/format/html/format-html-scss.ts

@@ -41,6 +41,7 @@ import {
   quartoBootstrapFunctions,
   quartoBootstrapMixins,
   quartoBootstrapRules,
+  quartoCodeFilenameRules,
   quartoCopyCodeRules,
   quartoDefaults,
   quartoFunctions,
@@ -98,6 +99,7 @@ function layerQuartoScss(
         quartoBootstrapRules(),
         quartoGlobalCssVariableRules(),
         quartoLinkExternalRules(),
+        quartoCodeFilenameRules(),
       ].join("\n"),
     },
     framework: {

src/format/html/format-html-shared.ts

@@ -134,6 +134,12 @@ export const quartoLinkExternalRules = () =>
     "_quarto-rules-link-external.scss",
   ));
 
+export const quartoCodeFilenameRules = () =>
+  Deno.readTextFileSync(formatResourcePath(
+    "html",
+    "_quarto-rules-code-filename.scss",
+  ));
+
 export const quartoTabbyRules = () =>
   Deno.readTextFileSync(formatResourcePath(
     "html",
@@ -190,6 +196,7 @@ export const quartoBaseLayer = (
   codeCopy = false,
   tabby = false,
   figResponsive = false,
+  codeFilename = false,
 ) => {
   const rules: string[] = [quartoRules()];
   if (codeCopy) {
@@ -201,6 +208,9 @@ export const quartoBaseLayer = (
   if (figResponsive) {
     rules.push(quartoFigResponsiveRules());
   }
+  if (codeFilename) {
+    rules.push(quartoCodeFilenameRules());
+  }
   if (format.render[kLinkExternalIcon]) {
     rules.push(quartoLinkExternalRules());
   }

src/format/reveal/format-reveal-theme.ts

@@ -150,7 +150,7 @@ export async function revealTheme(
     key: "reveal-theme",
     user: mergeLayers(...userLayers),
     quarto: mergeLayers(
-      quartoBaseLayer(format, true, true, false),
+      quartoBaseLayer(format, true, true, false, true),
       quartoLayer(),
     ),
     framework: revealFrameworkLayer(revealSrcDir),

src/resources/filters/quarto-pre/code-filename.lua

@@ -0,0 +1,58 @@
+-- for code blocks w/ filename create an enclosing div:
+-- <div class="code-with-filename">
+--   <div class="code-with-filename-file">
+--     <pre>filename.py</pre>
+--   </div>
+--   <div class="sourceCode" id="cb1" data-filename="filename.py">
+--     <pre></pre>
+--   </div>
+-- </div>
+
+local function codeBlockWithFilename(el, filename)
+  local filenameEl = pandoc.Div({pandoc.Plain{
+    pandoc.RawInline("html", "<pre>"),
+    pandoc.Strong{pandoc.Str(filename)},
+    pandoc.RawInline("html", "</pre>")
+  }}, pandoc.Attr("", {"code-with-filename-file"}))
+  return pandoc.Div(
+    { filenameEl, el:clone() },
+    pandoc.Attr("", {"code-with-filename"})
+  )
+end
+
+function codeFilename() 
+  return {
+    Blocks = function(blocks)
+  
+      -- transform ast for 'filename'
+      local foundFilename = false
+      local newBlocks = pandoc.List()
+      for _,block in ipairs(blocks) do
+        if block.attributes ~= nil and block.attributes["filename"] then
+          local filename = block.attributes["filename"]
+          if block.t == "CodeBlock" then
+            foundFilename = true
+            block.attributes["filename"] = nil
+            newBlocks:insert(codeBlockWithFilename(block, filename))
+          elseif block.t == "Div" and block.content[1].t == "CodeBlock" then
+            foundFilename = true
+            block.attributes["filename"] = nil
+            block.content[1] = codeBlockWithFilename(block.content[1], filename)
+            newBlocks:insert(block)
+          else
+            newBlocks:insert(block)
+          end
+        else
+          newBlocks:insert(block)
+        end
+      end
+    
+      -- if we found a file name then return the modified list of blocks
+      if foundFilename then
+        return newBlocks
+      else
+        return blocks
+      end
+    end
+  }  
+end

src/resources/filters/quarto-pre/quarto-pre.lua

@@ -51,6 +51,7 @@ import("../common/paths.lua")
 import("../common/timing.lua")
 import("results.lua")
 import("options.lua")
+import("code-filename.lua")
 import("shortcodes.lua")
 import("shortcodes-handlers.lua")
 import("outputs.lua")
@@ -101,6 +102,7 @@ local filterList = {
     figures(),
     theorems(),
     callout(),
+    codeFilename(),
     lineNumbers(),
     engineEscape(),
     panelInput(),

src/resources/formats/html/_quarto-rules-code-filename.scss

@@ -0,0 +1,36 @@
+.code-with-filename .code-with-filename-file {
+  margin-bottom: 0;
+  padding-bottom: 2px;
+  padding-top: 2px;
+  padding-left: 0.7em;
+  border: var(--quarto-border-width) solid var(--quarto-border-color);
+  border-radius: var(--quarto-border-radius);
+  border-bottom: 0;
+  border-bottom-left-radius: 0%;
+  border-bottom-right-radius: 0%;
+}
+
+.code-with-filename div.sourceCode,
+.reveal .code-with-filename div.sourceCode {
+  margin-top: 0;
+  border-top-left-radius: 0%;
+  border-top-right-radius: 0%;
+}
+
+.code-with-filename .code-with-filename-file pre {
+  margin-bottom: 0;
+}
+
+.code-with-filename .code-with-filename-file,
+.code-with-filename .code-with-filename-file pre {
+  background-color: rgba(219, 219, 219, 0.8);
+}
+
+.quarto-dark .code-with-filename .code-with-filename-file,
+.quarto-dark .code-with-filename .code-with-filename-file pre {
+  background-color: #555;
+}
+
+.code-with-filename .code-with-filename-file strong {
+  font-weight: 400;
+}