For AI agents: use /llms.txt for the Nakafa content index.
Markdown is a lightweight markup language for expressing document structure in plain text. Headings, lists, links, code blocks, and tables remain readable in the source and can be rendered into HTML or other formats.
That readable source is Markdown's main advantage. You can review changes line by line, store them in Git, and let a renderer decide the final typography without hiding the document behind formatting controls.
The following sample collects common syntax in one file. A hash introduces a heading, while surrounding markers express emphasis, links, code, and other structures:
# Heading Level 1
## Heading Level Two
### Heading Level Three
**Bold text**
*Italic text*
~~Strikethrough text~~
> Blockquote for important quotes
1. First ordered list item
2. Second ordered list item
3. Third ordered list item
- Unordered list item
- Another item
- Last item
[Link text](https://example.com)
`inline code`
```python
# Code block
def hello_world():
print("Hello, World!")
```
---
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data A | Data B | Data C |
| Data D | Data E | Data F |Keep the source file as the reviewed artifact and treat rendered files as reproducible output. A short workflow is enough: create, edit, validate, convert, and preview.
Create a file with the .md extension, write its content, and convert it with an installed tool such as Pandoc. HTML output is self-contained when --standalone is supplied. PDF output additionally needs a compatible PDF engine on the machine.
# Create new markdown file
touch document.md
# Edit with text editor
nano document.md
# Convert to HTML using pandoc
pandoc document.md -o document.html
# Convert to PDF when a supported PDF engine is installed
pandoc document.md -o document.pdf
# Preview on macOS; Linux desktops commonly use xdg-open
open document.htmlA command-line interface, or CLI, accepts textual commands through a shell. Each command has a program name, optional flags, and arguments such as paths.
CLI work is valuable because commands can be inspected, repeated, scripted, and reviewed. That power also makes exact paths and destructive flags important: the shell executes what you wrote, not what you intended.
Before changing files, confirm the current directory, inspect its contents, and move with explicit paths:
# Display current working directory
pwd
# List directory contents
ls
ls -l # detailed format
ls -la # including hidden files
# Change directory
cd "$HOME/documents"
cd .. # go up one level
cd ~ # go to home directory
cd - # return to previous directory
# Create new directory
mkdir new_project
mkdir -p project/src/components # create directory hierarchyFile commands act on real paths immediately. Inspect the target before a removal, quote paths that may contain spaces, and avoid recursive force flags unless the exact directory is proven disposable.
# Copy files
cp source.txt destination.txt
cp -r source_folder/ destination_folder/
# Move or rename files
mv old_name.txt new_name.txt
mv file.txt /path/to/new/location/
# Inspect before deleting
pwd
ls -la unwanted_folder
rm unwanted_file.txt
rm -r unwanted_folder # recursive and irreversible; verify this exact path first
# View file contents
cat file.txt # display entire contents
head -10 file.txt # first 10 lines
tail -10 file.txt # last 10 lines
less file.txt # view with navigationA small build script makes the conversion repeatable. It should fail when a command fails, create its own output directory, quote every path, and handle the case where no source file exists:
# Setup markdown project
mkdir my-documentation
cd my-documentation
# Directory structure
mkdir -p {src,build,images,assets}
# Create markdown files
touch src/index.md src/getting-started.md src/api-reference.md
# Automate build with script
cat << 'EOF' > build.sh
#!/bin/bash
set -eu
echo "Building documentation..."
mkdir -p build
# Convert all .md files to .html
for file in src/*.md; do
[ -e "$file" ] || continue
basename=$(basename "$file" .md)
pandoc "$file" -o "build/$basename.html" --standalone
echo "Converted: $file -> build/$basename.html"
done
echo "Build completed!"
EOF
# Make script executable
chmod +x build.sh
# Run build
./build.shUse tools from their official installation channels, then verify the installed commands before relying on them in a script. Pandoc converts documents, while a Markdown linter checks source conventions:
# Verify required tools
command -v pandoc
command -v markdownlint
# Check Markdown sources
markdownlint "docs/**/*.md"
# Convert markdown to various formats
pandoc input.md -o output.pdf
pandoc input.md -o output.docx
pandoc input.md -o output.epub
# With custom template
pandoc input.md -o output.html --template=custom.htmlKeep authored Markdown in version control, validate before conversion, build into a replaceable output directory, and review the diff before committing:
# Reproducible local documentation build
cat << 'EOF' > update-docs.sh
#!/bin/bash
set -eu
SOURCE_DIR="docs"
OUTPUT_DIR="site"
STAGING_DIR=$(mktemp -d)
trap 'rm -rf "$STAGING_DIR"' EXIT
mapfile -d '' source_files < <(find "$SOURCE_DIR" -type f -name "*.md" -print0)
if [ "${#source_files[@]}" -eq 0 ]; then
echo "No Markdown sources found" >&2
exit 1
fi
markdownlint "${source_files[@]}"
for file in "${source_files[@]}"; do
relative_path=${file#"$SOURCE_DIR"/}
output_file="$STAGING_DIR/${relative_path%.md}.html"
mkdir -p "$(dirname "$output_file")"
pandoc "$file" -o "$output_file" --standalone
done
[ ! -e "$OUTPUT_DIR" ] || rm -r -- "$OUTPUT_DIR"
mv "$STAGING_DIR" "$OUTPUT_DIR"
trap - EXIT
EOF
chmod +x update-docs.sh
./update-docs.sh
# Review authored changes before committing
git diff --check
git diff -- docsThe final example creates four source pages and combines them into one standalone HTML document. Every input path is explicit, so a missing page fails the build instead of being silently skipped:
# Setup project structure
mkdir ai-project-docs
cd ai-project-docs
# Create directory structure
mkdir -p docs/api docs/tutorials docs/guides scripts build
# Create main documentation files
cat << 'EOF' > docs/README.md
# AI Project Documentation
## Overview
Complete documentation for AI programming projects.
## Structure
- [API Reference](api/README.md)
- [Tutorials](tutorials/README.md)
- [User Guides](guides/README.md)
EOF
# Create the referenced pages
cat << 'EOF' > docs/api/README.md
# API Reference
Describe each public interface and include one verified example.
EOF
cat << 'EOF' > docs/tutorials/README.md
# Tutorials
Guide the reader through one complete task.
EOF
cat << 'EOF' > docs/guides/README.md
# User Guides
Explain recurring workflows and their safety boundaries.
EOF
# Create automated build script
cat << 'EOF' > scripts/build-docs.sh
#!/bin/bash
set -eu
mkdir -p build
pandoc docs/README.md docs/api/README.md docs/tutorials/README.md docs/guides/README.md --standalone --output build/index.html
echo "Documentation build completed!"
EOF
chmod +x scripts/build-docs.sh
# Run the build
./scripts/build-docs.shMarkdown keeps document structure readable in source control, while the CLI makes validation and conversion repeatable. A trustworthy workflow preserves that boundary: edit the source, verify commands and paths, regenerate output, and review the resulting changes.