Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.
Last updated on

Literal include (::literal-include)

↑ Docs content model

The ::literal-include directive displays the contents of a file inside a code block, optionally with syntax highlighting.

When to use​

Use ::literal-include to show real, runnable source (a Python module, a config file) in a code block without copying it into the page, so the documented code stays in sync with the actual file. Use Include instead to inline rendered Markdown rather than show a file as code.

Technical details​

Markdown
::literal-include[<filepath>]

OR

::literal-include[<filepath>]{language='<language>'}

The filepath is relative to the docs/web/includes/ directory, and the included file must exist within that directory. A syntax-highlighting language may optionally be specified via the language option.

Rules​

  • The filepath is relative to docs/web/includes/, and the file must exist there.
  • The language option is optional; when omitted, the code block has no syntax highlighting.

Style​

  • Set language whenever the file has a known language so the code block is highlighted.

Template​

Markdown
::literal-include[filepath]{language='python'}

Examples​

Example:

Markdown
::literal-include[code-examples/unit-testing/myfunctions.py]

::literal-include[code-examples/unit-testing/myfunctions.py]{language='python'}

Output:

import pyspark
from pyspark.sql import SparkSession
from pyspark.sql.functions import col

# Because this file is not a Databricks notebook, you
# must create a Spark session. Databricks notebooks
# create a Spark session for you by default.
spark = SparkSession.builder \
                    .appName('integrity-tests') \
                    .getOrCreate()

# Does the specified table exist in the specified database?
def tableExists(tableName, dbName):
  return spark.catalog.tableExists(f"{dbName}.{tableName}")

# Does the specified column exist in the given DataFrame?
def columnExists(dataFrame, columnName):
  if columnName in dataFrame.columns:
    return True
  else:
    return False

# How many rows are there for the specified value in the specified column
# in the given DataFrame?
def numRowsInColumnForValue(dataFrame, columnName, columnValue):
  df = dataFrame.filter(col(columnName) == columnValue)

  return df.count()
Python
import pyspark
from pyspark.sql import SparkSession
from pyspark.sql.functions import col

# Because this file is not a Databricks notebook, you
# must create a Spark session. Databricks notebooks
# create a Spark session for you by default.
spark = SparkSession.builder \
                    .appName('integrity-tests') \
                    .getOrCreate()

# Does the specified table exist in the specified database?
def tableExists(tableName, dbName):
  return spark.catalog.tableExists(f"{dbName}.{tableName}")

# Does the specified column exist in the given DataFrame?
def columnExists(dataFrame, columnName):
  if columnName in dataFrame.columns:
    return True
  else:
    return False

# How many rows are there for the specified value in the specified column
# in the given DataFrame?
def numRowsInColumnForValue(dataFrame, columnName, columnValue):
  df = dataFrame.filter(col(columnName) == columnValue)

  return df.count()

Used in​

Content atoms appear in any page section. Literal includes are common in Procedure and tutorials, where documented code should match a real source file.

On this page