Help:Shortcode Readfile

Render a code-block from a file.

Readfile
Shortcode
Description
TypeMarkdown Shortcode
Nested?false
Shortcodereadfile
Return TypeMarkdown
Short Description
Render a file relative to the project root as Markdown code block.
Development
MaintainerMichael Sasser

The readfile shortcode is used to render a code block from a source code file. On this page the shortcode is used to render the code, you see below.

Parameters

The post shortcode has the following parameters:

ParameterDescription
pathThe absulute path, relative to the project root, to the file to render as code block
typeOverwrite the file type used for highlighting.

File Type

By default the extension of the file is used to derive the file type.

Examples

Type derived from file extension 

{{% readfile path=".prettierrc.yaml" %}}
Rendered
---
# https://github.com/NiklasPor/prettier-plugin-go-template
goTemplateBracketSpacing: true

overrides:
  - files: "*.html"
    options:
      parser: "go-template"
  - files: "*.js"
    options:
      trailingComma: es5
      tabWidth: 4
      singleQuote: true
      semi: true
  - files: "*.scss"
    options:
      tabWidth: 2
      singleQuote: false

Type overwritten 

{{% readfile path="theme.toml" type="toml" %}}
Rendered
name = "Doks"
license = "MIT"
licenselink = "https://github.com/h-enk/doks/blob/master/LICENSE"
description = "Hugo theme helping you build modern documentation websites that are secure, fast, and SEO-ready — by default."

homepage = "https://github.com/h-enk/doks"
demosite = "https://doks.netlify.app"

tags = ["landing page", "documentation", "blog", "minimal", "modern", "customizable", "search", "dark mode", "bootstrap"]
features = ["security aware", "fast by default", "seo-ready", "development tools", "bootstrap framework", "netlify-ready", "full text search", "page layouts", "dark mode"]

[author]
  name = "Henk Verlinde"
  homepage = "https://henkverlinde.com"

Code

Below you find the implementation of the shortcode.

HTML

Defined in layouts/shortcodes/readfile.html.

This code is licensed under the MIT license.
<!-- 

  ReadFile Shortcode 
  ==================

  Contributors: Michael Sasser
  Maintainer: Michael Sasser
  License: MIT
  Version: 1
  Child Shortcodes: None
  Parent Shortcodes: None

  LAYOUT: /layouts/shortcodes/readfile.html
  DOCS:   /content/<language>/wiki/Help:Shortcode_ReadFile.md
  LIB:    highlight.js
  SCRIPT: /assets/js/highlight.js 

  Note
  ----

  In order to render a specific file type you need to make sure, the file
  type is supported by the highlight.js library end enabled in the script
  listed above.

  Description
  -----------

  Use ReadFile shortcode to render a file relative to the project root as 
  Markdown code block. The file type is derived from the file extension. 
  Optionally the file type can be overwritten.

  Changelog
  =========

  Version 1 (2022-07-17)
  ----------------------

  Initial release

-->

{{- $path := .Get "path" -}}                                        <!-- Mandatory parameter -->
{{- $type := .Get "type" | default (trim (path.Ext $path) ".") -}}  <!-- Optional parameter -->

{{- with os.FileExists $path -}}

  <!-- Get file content -->
  {{- $file_content := readFile $path -}}

  <!-- Print the output as markdown code block -->
  {{- ( print "```" $type "\n" ($file_content) "\n" "```" ) | markdownify -}}

{{- else -}}
    {{ errorf "Failed to process readfile shortcode: %s. The file \"%s\" does not exist." $.Position $path }}
{{- end -}}

Download

Copy the source code above or use the download link below to use this file on your website according to the license.

  • Readfile Shortcode
    readfile.html ❘ 1.43 KB
  • md5   402af27526f53e0a3a15f5838416d5a6
  • sha1   935d9784596f0d06c0cdaf6de255ed9e3efeb5c9
  • sha256   20b61ddaafc8dce579fb04446b8691a8543a395c770950d3ee116c6dbe87408e

JavaScript

Defined in: /assets/js/highlight.js
Uses: highlight.js (Package: NPM , License: BSD-3-Clause )

This code is licensed under the MIT license.
/*

  ReadFile Shortcode
  ==================

  Contributors: Michael Sasser
  Maintainer: Michael Sasser
  License: MIT
  Version: 1
  Child Shortcodes: None
  Parent Shortcodes: None

  LAYOUT: /layouts/shortcodes/readfile.html
  DOCS:   /content/<language>/wiki/Help:Shortcode_ReadFile.md
  LIB:    highlight.js
  SCRIPT: /assets/js/highlight.js

*/

import hljs from 'highlight.js/lib/core';

import javascript from 'highlight.js/lib/languages/javascript';
import json from 'highlight.js/lib/languages/json';
import bash from 'highlight.js/lib/languages/bash';
import xml from 'highlight.js/lib/languages/xml';
import scss from 'highlight.js/lib/languages/scss';
import ini from 'highlight.js/lib/languages/ini';
import yaml from 'highlight.js/lib/languages/yaml';
import markdown from 'highlight.js/lib/languages/markdown';
import c from 'highlight.js/lib/languages/c';
import python from 'highlight.js/lib/languages/python';
import pythonRepl from 'highlight.js/lib/languages/python-repl';

hljs.registerLanguage('javascript', javascript);
hljs.registerLanguage('json', json);
hljs.registerLanguage('bash', bash);
hljs.registerLanguage('html', xml);
hljs.registerLanguage('scss', scss);
hljs.registerLanguage('ini', ini);
hljs.registerLanguage('toml', ini);
hljs.registerLanguage('yaml', yaml);
hljs.registerLanguage('md', markdown);
hljs.registerLanguage('c', c);
hljs.registerLanguage('python', python);
hljs.registerLanguage('python-repl', pythonRepl);

document.addEventListener('DOMContentLoaded', () => {
  document.querySelectorAll('pre code:not(.language-mermaid)').forEach((block) => {
    hljs.highlightElement(block);
  });
});

Download

Copy the source code above or use the download link below to use this file on your website according to the license.

  • Highlight Script
    highlight.js ❘ 1.65 KB
  • md5   6ece175717739f2174e3938befb6288f
  • sha1   1b94fec979474cacadeb718418d4f5b4cc03ad8d
  • sha256   915f6edbea223ef6253012386cf14b8388ae872203439777db4f9f3e294dad9a
Last modified on February 26, 2024
Edit this page on GitLab
Categories
Contributors
Help, Contribute and ShortcodeMichael Sasser