Skip to content

extract.md

Latest commit

 

History

History
274 lines (196 loc) · 6.88 KB

extract.md

File metadata and controls

274 lines (196 loc) · 6.88 KB
Raw

Extract Command

The extract command exports raw article content from ZIM archive files to stdout for redirection to files or piping to other commands. Unlike read, which formats content for terminal display, extract provides the unmodified content as stored in the ZIM file.

Overview

The extract command outputs article content in its original format without any processing or formatting. This makes it ideal for:

  • Exporting HTML articles with full markup intact
  • Saving binary content (images, PDFs, etc.) to files
  • Piping content to other tools for further processing
  • Creating backups of specific articles

Usage

zim extract <file.zim or name> <article>

Arguments

  • <file.zim or name> - Path to ZIM file or name of library file
  • <article> - Article title to extract (exact match preferred)

Output

Content Format

The extract command writes article content to stdout in its original format:

  • HTML articles: Full HTML markup with embedded CSS and JavaScript
  • Text articles: Plain text content exactly as stored
  • Binary content: Raw binary data (images, fonts, etc.)

Redirection to Files

Use shell redirection to save content to files:

# Save HTML article
zim extract wikipedia "Main_Page" > main_page.html

# Save binary image
zim extract commons "Logo.png" > logo.png

# Save text article
zim extract wiki "Article_Title" > article.txt

Article Lookup

The extract command uses multiple search strategies to find articles:

Search Strategy

  1. Exact match - Tries exact article title in namespace 'C' (modern format)
  2. Legacy namespace - Falls back to namespace 'A' (old format)
  3. Underscore/Space variants - Tries replacing:
    • Underscores with spaces: Main_Page → Main Page
    • Spaces with underscores: Main Page → Main_Page

Examples

# Exact match with underscores
zim extract wikipedia "Python_(programming_language)"

# Space variant (also works)
zim extract wikipedia "Python (programming language)"

# Both work for standard articles
zim extract wikipedia "Main_Page"
zim extract wikipedia "Main Page"

Output Examples

HTML Article

zim extract wikipedia "Albert_Einstein" > einstein.html

The file einstein.html contains the complete HTML document:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Albert Einstein - Wikipedia</title>
    <!-- CSS and metadata -->
</head>
<body>
    <div class="mw-parser-output">
        <p><b>Albert Einstein</b> (14 March 1879 – 18 April 1955)...</p>
        <!-- Full article content with all markup -->
    </div>
</body>
</html>

Binary Image

zim extract wikicommons "Example_logo.svg" > logo.svg

The file logo.svg contains raw SVG data for use in other applications.

Piping to Other Commands

# Extract and count words in HTML (stripping tags first)
zim extract wikipedia "Article" | grep -o '<p>.*</p>' | wc -w

# Extract and compress
zim extract wikipedia "Large_Article" | gzip > article.html.gz

# Extract and process with Python
zim extract wikipedia "Data" | python3 process_html.py

Use Cases

Exporting Multiple Articles

# Export several articles to a directory
mkdir -p articles/
zim extract wikipedia "Physics" > articles/physics.html
zim extract wikipedia "Chemistry" > articles/chemistry.html
zim extract wikipedia "Biology" > articles/biology.html

Creating Offline Backups

# Backup important articles with full formatting
zim extract wikipedia "COVID-19_pandemic" > covid_backup.html
zim extract wikipedia "Climate_change" > climate_backup.html

Extracting Media Resources

# Save images for use in documents
zim extract commons "World_map.png" > map.png
zim extract commons "Flag_of_France.svg" > flag.svg

Content Processing Pipelines

# Extract HTML and convert to Markdown
zim extract wikipedia "Article" | pandoc -f html -t markdown > article.md

# Extract and clean HTML
zim extract wikipedia "Article" | tidy -m -i - clean_article.html

Error Handling

Common Errors

Error: article not found: Nonexistent Article

Solution: Check the article title using zim list or zim search:

zim search wikipedia "Nonexistent"
zim list wikipedia | grep -i nonexistent
Error: failed to read article content: unexpected EOF

Solution: The ZIM file may be corrupted. Try:

zim info wikipedia  # Check file integrity
Error: failed to write output: broken pipe

Solution: Occurs when the receiving command terminates early. This is normal behavior when using head or similar commands.

Comparison with Other Commands

Command Output Format Use Case
zim read Formatted for terminal Reading articles in console
zim extract Original format Saving files, piping to tools
zim serve Rendered in browser Interactive browsing

When to Use Extract vs Read

Use extract when:

  • You need the original HTML with all markup
  • Saving content to a file for later use
  • Processing content with other tools
  • Exporting binary data (images, PDFs, etc.)

Use read when:

  • Reading articles directly in the terminal
  • You want clean text output without HTML tags
  • Quick viewing without saving to file

Performance Considerations

  1. Exact matches are faster than variants - use underscores when known
  2. Large articles (like long Wikipedia pages) may take time to extract
  3. Binary content is streamed efficiently regardless of size
  4. No processing overhead - extract is faster than read for large HTML articles

Examples

Example 1: Export Single Article

zim extract wikipedia "Artificial_intelligence" > ai.html

Output: Full HTML article saved to ai.html

Example 2: Export Multiple Articles

# Create a collection of physics articles
for topic in "Quantum_mechanics" "Relativity" "Thermodynamics"; do
    zim extract wikipedia "$topic" > "${topic}.html"
done

Example 3: Extract and Convert Format

# Extract HTML and convert to Markdown
zim extract wikipedia "Go_(programming_language)" | \
  pandoc -f html -t markdown -o go-lang.md

Example 4: Extract Binary Resources

# Save a map image
zim extract commons "World_map_(physical).png" > world_map.png

# Save a font file
zim extract wikipedia "DejaVuSans.ttf" > dejavu.ttf

Example 5: Pipeline Processing

# Extract and count article sections (h2 tags)
zim extract wikipedia "Large_Article" | \
  grep -c '<h2' > section_count.txt

# Extract and validate HTML
zim extract wikipedia "Article" | \
  tidy -qe 2>&1

Related Commands

  • zim read - Read articles with terminal formatting
  • zim list - List all articles in a ZIM file
  • zim search - Find articles by keyword
  • zim serve - Browse ZIM content via web interface
  • zim info - Display ZIM file metadata