Writing Text with Markdown
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.
Basic Markdown Syntax
The following sample collects common syntax in one file. A hash introduces a heading, while surrounding markers express emphasis, links, code, and other structures:
The example uses Markdown features supported by Pandoc and GitHub Flavored Markdown. Tables and ~~strikethrough~~ are extensions, so not every Markdown renderer supports them. The shell examples use Bash on macOS or Linux. Adapt example paths to your practice directory.
# 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 |Markdown Workflow
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. With --standalone, HTML output includes the document header and body. Linked images and styles remain separate unless explicitly embedded. 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 --standalone -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.htmlCommand Line Interface Basics
A 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 commands can be inspected, repeated, scripted, and reviewed. The shell follows the written path and every flag exactly, so resolve the target and review destructive flags before running the command.
Directory Navigation and Exploration
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
mkdir -p "$HOME/markdown-practice"
cd "$HOME/markdown-practice"
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 and Directory Operations
File 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 navigationIntegrating Markdown with CLI
A 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.shCLI Tools for Markdown
Use 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.htmlBest Practices for CLI and Markdown
Keep authored Markdown in version control, validate before conversion, build into a replaceable output directory, and review the diff before committing:
The site directory in this example contains only generated output and is replaced by the build. Keep authored files in docs, not in site.
# Reproducible local documentation build
cat << 'EOF' > update-docs.sh
#!/bin/bash
set -eu
SOURCE_DIR="docs"
OUTPUT_DIR="site"
STAGING_DIR=$(mktemp -d "./.site-build.XXXXXX")
trap 'rm -rf "$STAGING_DIR"' EXIT
source_files=()
while IFS= read -r -d '' file; do
source_files+=("$file")
done < <(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 -- docsReal Project Example
The final example creates four source pages and combines them into one standalone HTML document. Every input path is explicit, so the build fails when a page is missing:
# 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
## What the Tool Does
Complete documentation for AI programming projects.
## How a Document Is Organized
- [API Reference](#api)
- [Tutorials](#tutorials)
- [User Guides](#guides)
EOF
# Create the referenced pages
cat << 'EOF' > docs/api/README.md
# API Reference {#api}
Describe each public interface and include one verified example.
EOF
cat << 'EOF' > docs/tutorials/README.md
# Tutorials {#tutorials}
Guide the reader through one complete task.
EOF
cat << 'EOF' > docs/guides/README.md
# User Guides {#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 version control. With a CLI, the same validation and conversion steps can be run again. A trustworthy workflow preserves that boundary: edit the source, verify commands and paths, regenerate output, and review the resulting changes.