Shellscribe is a documentation generator for shell scripts. It extracts specially formatted comments from your bash scripts and generates clear, structured, and professional documentation in Markdown format.
- Generates elegant Markdown documentation
- Automatically extracts script metadata (author, version, license, etc.)
- Supports documentation of functions, arguments, and examples
- Supports exit codes and stdout/stderr messages
- Transforms GitHub usernames into links to their profiles
- Detects and documents ShellCheck directives
- Supports dependency documentation (requires, provides, calls, used-by)
- Optimized for memory efficiency with large projects
- Recursive processing of directories
- Supports excluding scripts from documentation using @skip annotation
- A C compiler (GCC or Clang)
- CMake (>= 3.10)
You can quickly install Shellscribe using our installation script available in the GitHub releases:
curl -sL https://github.com/tomcdj71/shellscribe/releases/latest/download/scribe
mv scribe /usr/local/binFor Debian-based distributions, you can download and install the pre-built .deb package:
RELEASE_URL=$(curl -s https://api.github.com/repos/tomcdj71/shellscribe/releases/latest |
grep "browser_download_url.*deb" |
cut -d : -f 2,3 |
tr -d \")
wget "$RELEASE_URL" -O shellscribe.deb
sudo dpkg -i shellscribe.debInstructions on how the .deb package is built
# Clone the repository
git clone https://github.com/tomcdj71/shellscribe.git
cd shellscribe
# Create the build directory
mkdir build && cd build
# Configure and compile
cmake ..
cmake --build .
# Install (optional)
sudo cmake --install .scribe path/to/your_script.shBy default, Shellscribe outputs to stdout, which can be redirected to a file:
Shellscribe can process entire directories of shell scripts recursively:
scribe path/to/scripts_directoryThe documentation will be saved to the configured output directory (default: ./docs).
Usage: scribe [OPTIONS] FILE...
Options:
--help, -h Display this help message
--version, -v Display the version
--config-file=FILE Specify a custom configuration file
Shellscribe uses a configuration file named .scribeconf in the current directory by default. For a complete list of configuration options, see Configuration Reference.
Example .scribeconf:
doc_path=./docs
show_shellcheck=true
shellcheck_display=sequential
arguments_display=table
Shellscribe uses a specific comment format to extract documentation:
#!/usr/bin/env bash
# @file modules/example.sh
# @project MyProject
# @version 1.0.0
# @description An example module with useful functions
# @author John Doe (johndoe)
# @author_contact johndoe@example.com
# @license BSD-3 Clause
# @copyright Copyright (C) 2025, MyOrg# @brief Installs a package with apt
# @description Attempts to install a package using apt-get
# @arg $1 string Name of the package to install
# @requires root_access
# @provides package_installation
# @calls apt-get
# @example
# install_package "curl"
# @exitcode 0 Installation successful
# @exitcode 1 Installation failed
# @stdout Installation status message
install_package() {
local package=$1
echo "Installing $package..."
apt-get install -y "$package" > /dev/null 2>&1
if [ $? -eq 0 ]; then
echo "Installation of $package successful"
return 0
else
echo "Installation of $package failed" >&2
return 1
fi
}Shellscribe supports documenting dependencies between functions:
@requires: Functions or components required by this function@provides: Services or features provided by this function@calls: External commands or tools called by this function@used-by: Functions that use this function
# @function prepare_environment
# @brief Sets up the execution environment
# @requires bash
# @provides environment_setup
# @calls mkdir
prepare_environment() {
mkdir -p /tmp/workspace
}Shellscribe can detect and document ShellCheck directives in your code:
# shellcheck disable=SC2086
# @function join_arguments
# @brief Joins all arguments with a space
join_arguments() {
echo $*
}To include ShellCheck directives in the documentation, enable the show_shellcheck option in your configuration. You can control the display format by setting the shellcheck_display option to either table or sequential.
You can exclude specific scripts from documentation generation by adding the @skip annotation in the file metadata:
#!/usr/bin/env bash
# @file internal_script.sh
# @skip
# @description This script will not be included in the documentationScripts with the @skip annotation will be ignored during documentation generation, which is useful for utility scripts, tests, or other internal files that don't need public documentation.
Here's an example of the generated documentation: docs: example
Contributions are welcome! Here's how to participate:
- Fork the project
- Create a branch for your feature (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the Apache 2.0 Clause - see the LICENSE file for details.
© tomcdj71 2025