Document frontmatter (#46)

Author: fonsp

src/assets/img/compress_pngs.sh

@@ -1,7 +1,8 @@
 #!/bin/bash
 
 # PNG Compression Script
-# Compresses all PNG files in the current directory using pngquant
+# Compresses PNG files using pngquant
+# Can compress all PNGs in current directory or a specific file
 # Shows before/after sizes and calculates total savings
 # Skips files that are already compressed (8-bit or limited palette)
 
@@ -28,34 +29,87 @@ if ! command -v identify &> /dev/null; then
     exit 1
 fi
 
-# Check if there are PNG files in the current directory
-if ! ls *.png >/dev/null 2>&1; then
-    echo -e "${RED}No PNG files found in the current directory.${NC}"
-    exit 1
-fi
+# Parse arguments
+FORCE=false
+TARGET_FILE=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --force)
+            FORCE=true
+            shift
+            ;;
+        --help)
+            echo -e "${BLUE}Usage:${NC}"
+            echo -e "  ./compress_pngs.sh [OPTIONS] [FILENAME]"
+            echo -e ""
+            echo -e "${BLUE}Options:${NC}"
+            echo -e "  --force    Force compress all files (not recommended)"
+            echo -e "  --help     Show this help"
+            echo -e ""
+            echo -e "${BLUE}Examples:${NC}"
+            echo -e "  ./compress_pngs.sh                    # Compress all PNGs in current directory"
+            echo -e "  ./compress_pngs.sh image.png          # Compress only image.png"
+            echo -e "  ./compress_pngs.sh --force             # Force compress all files"
+            exit 0
+            ;;
+        -*)
+            echo -e "${RED}Unknown option: $1${NC}"
+            echo "Use --help for usage information"
+            exit 1
+            ;;
+        *)
+            if [[ -z "$TARGET_FILE" ]]; then
+                TARGET_FILE="$1"
+            else
+                echo -e "${RED}Error: Only one filename can be specified${NC}"
+                exit 1
+            fi
+            shift
+            ;;
+    esac
+done
 
-echo -e "${BLUE}🖼️  PNG Compression Script${NC}"
-echo -e "${BLUE}=========================${NC}\n"
+# Determine which files to process
+PNG_FILES=()
+if [[ -n "$TARGET_FILE" ]]; then
+    # Single file specified
+    if [[ ! -f "$TARGET_FILE" ]]; then
+        echo -e "${RED}Error: File '$TARGET_FILE' does not exist.${NC}"
+        exit 1
+    fi
+    
+    # Check if it's a PNG file (case insensitive)
+    if [[ ! "$TARGET_FILE" =~ \.[Pp][Nn][Gg]$ ]]; then
+        echo -e "${RED}Error: '$TARGET_FILE' is not a PNG file.${NC}"
+        exit 1
+    fi
+    
+    PNG_FILES=("$TARGET_FILE")
+    echo -e "${BLUE}🖼️  PNG Compression Script - Single File Mode${NC}"
+    echo -e "${BLUE}=============================================${NC}\n"
+else
+    # Process all PNG files in current directory
+    if ! ls *.png >/dev/null 2>&1; then
+        echo -e "${RED}No PNG files found in the current directory.${NC}"
+        exit 1
+    fi
+    
+    for file in *.png; do
+        if [[ -f "$file" ]]; then
+            PNG_FILES+=("$file")
+        fi
+    done
+    
+    echo -e "${BLUE}🖼️  PNG Compression Script - Directory Mode${NC}"
+    echo -e "${BLUE}===========================================${NC}\n"
+fi
 
 # Quality setting (can be modified)
 QUALITY="65-80"
 
-# Option to create backups
-BACKUP=false
-FORCE=false
-if [[ "$1" == "--backup" ]]; then
-    BACKUP=true
-    echo -e "${YELLOW}Creating backups of original files...${NC}"
-elif [[ "$1" == "--force" ]]; then
-    FORCE=true
+if [[ "$FORCE" == true ]]; then
     echo -e "${YELLOW}Force mode: will compress all files regardless of current state${NC}"
-elif [[ "$1" == "--help" ]]; then
-    echo -e "${BLUE}Usage:${NC}"
-    echo -e "  ./compress_pngs.sh           # Normal compression (skips already compressed)"
-    echo -e "  ./compress_pngs.sh --backup  # Create backups before compression"
-    echo -e "  ./compress_pngs.sh --force   # Force compress all files (not recommended)"
-    echo -e "  ./compress_pngs.sh --help    # Show this help"
-    exit 0
 fi
 
 # Function to check if PNG is already compressed (8-bit or limited colors)
@@ -83,7 +137,7 @@ TO_COMPRESS=()
 ALREADY_COMPRESSED=()
 FAILED_ANALYSIS=()
 
-for file in *.png; do
+for file in "${PNG_FILES[@]}"; do
     if [[ -f "$file" ]]; then
         if [[ "$FORCE" == true ]]; then
             TO_COMPRESS+=("$file")
@@ -122,13 +176,6 @@ fi
 
 echo ""
 
-# Create backup if requested
-if [[ "$BACKUP" == true ]]; then
-    mkdir -p originals
-    cp "${TO_COMPRESS[@]}" originals/
-    echo -e "${GREEN}✅ Backups created in 'originals' folder${NC}\n"
-fi
-
 # Compress each PNG file that needs compression
 echo -e "${BLUE}🔄 Compressing files...${NC}"
 COMPRESSED_COUNT=0
@@ -173,10 +220,6 @@ echo -e "Size after:  ${TOTAL_AFTER}"
 echo -e "Space saved: ${SAVINGS_KB}KB"
 echo -e "${GREEN}Reduction: ${SAVINGS_PERCENT}%${NC}"
 
-if [[ "$BACKUP" == true ]]; then
-    echo -e "${YELLOW}\n💡 Original files are backed up in 'originals' folder${NC}"
-fi
-
 echo -e "\n${BLUE}ℹ️  Note: This uses lossy compression (reduces colors to ~256)${NC}"
 echo -e "${BLUE}   Quality setting used: ${QUALITY}${NC}"
 echo -e "${BLUE}   Skipped files with ≤8-bit depth or ≤256 colors${NC}"

src/assets/img/frontmatter heatmap screenshot.png

@@ -18,9 +18,4 @@ After writing your Pluto notebook, you have a couple options to **export** your
 > Press the **Share** button in the top right.
 > 
 > <img src="$(root_url)/assets/img/Share button screenshot.png" alt="Screenshot of the Share button" width="1532" height="282">
-> 
-> ### Step 3
-> Choose "Notebook file".
-> 
-> <img src="$(root_url)/assets/img/Export options screenshot.png" alt="Screenshot of the export options" width="1804" height="472">
 

src/en/docs/export.jlmd

@@ -0,0 +1,72 @@
+---
+title: "📰 Frontmatter"
+description: "How to use frontmatter in Pluto.jl notebooks."
+tags: ["docs", "publishing", "frontmatter", "yaml", "markdown", "file", "export", "share", "web"]
+layout: "md.jlmd"
+order: 7
+---
+
+# Frontmatter <span id="frontmatter"></span>
+
+Frontmatter is a way to add metadata to a Pluto.jl notebook, such as the title, description, authors, cover image, license, date and more. This data is used when **sharing notebooks online**, using [Pluto HTML exports](../export-html/), [`PlutoUI.NotebookCard`](https://featured.plutojl.org/basic/plutoui.jl#NotebookCard), [PlutoSliderServer](https://github.com/JuliaPluto/PlutoSliderServer.jl), [PlutoPages](https://github.com/JuliaPluto/PlutoPages.jl) or [pluto.land](https://pluto.land).
+
+For example, the [featured notebooks](../featured-notebooks/) use frontmatter. When you see the list of all featured notebooks, notice how they all have a title, description, cover image and authors. And they are 
+
+
+## The frontmatter GUI
+When editing a Pluto notebook, you can open the frontmatter editor by clicking the "Share button" in the top right.
+
+<img src="$(root_url)/assets/img/Share button screenshot.png" alt="Screenshot of the Share button" width="1532" height="282">
+
+In the share menu, click the <img src="https://cdn.jsdelivr.net/gh/ionic-team/ionicons@5.5.1/src/svg/newspaper-outline.svg" alt="📰" width=17px style="filter: var(--image-filters);"> icon to open the frontmatter editor.
+
+
+<blockquote style="max-height: 300px; overflow-y: auto;">
+<p>Here is a screenshot of the frontmatter editor. Scroll down to see more.</p>
+
+<img src="$(root_url)/assets/img/frontmatter heatmap screenshot.png" alt="Screenshot of the frontmatter editor" width="854" height="1570">
+</blockquote>
+
+In this editor, you can edit fields and add new fields. You are free to enter any data that you want (which you might want to [use](#Pluto.frontmatter) in your custom scripts), but some frontmatter entries have special meaning in the Pluto ecosystem.
+
+### Special frontmatter entries
+The following keys have special meaning:
+- **`title`** – the title of the document. When not used, the notebook filename is used as title. This is used in Pluto.jl HTML exports as the `<title>` tag.
+- **`description`** – the description of the document. This is used in Pluto.jl HTML exports as the `<meta name="description" content="...">` tag.
+- **`image`** – the URL of the cover image of the document.
+- **`date`** – the date of the document.
+- **`license`** – the license of the document.
+- **`tags`** – a vector of tags for the document, used by the PlutoPages.jl sidebar and search, and PlutoSliderServer.jl.
+- **`layout`** – the PlutoPages.jl layout file of the document.
+- **`order`** – the order of the document within its category.
+
+### Open Graph (OG) tags
+The following keys are used as [Open Graph (OG) tags](https://ogp.me/) in Pluto.jl HTML exports (using `<meta property="og:...">`): 
+
+`title`, `type`, `description`, `image`, `article:tag`, `url`, `audio`, `video`, `site_name`, `locale`, `locale:alternate`, `determiner`. 
+
+Setting these values helps with sharing notebooks on social media and search engine optimization.
+
+### The `author` field
+There is also a vector `author` that is used to provide the authors of the notebook. The following fields have special meaning in the Pluto ecosystem:
+- **`name`** – the name of the author.
+- **`url`** – the URL of the author's website. If this is a github user/organization URL, the author's avatar will be shown in the notebook.
+- **`image`** - the URL of the author's avatar. This is not needed if the `url` is a github URL.
+
+
+## PlutoPages.jl
+If you are using [PlutoPages.jl](https://github.com/JuliaPluto/PlutoPages.jl) to write your website, you should at least set the following frontmatter entries for every page: `layout` and `tags`. (`layout` is the name of the layout file in the `src/_includes/` directory.)
+
+
+## Featured notebooks
+If you are writing a featured notebook, check out other featured notebook files to see which frontmatter entries are required.
+
+
+## <span id="Pluto.frontmatter">Accessing frontmatter from Julia</span>
+If you are writing a script to process Pluto notebooks, you can access the frontmatter data using the **`Pluto.frontmatter`** function. This function takes a notebook path as an argument, and returns a `Dict` with the frontmatter data.
+
+```julia
+path = "/path/to/notebook.jl"
+frontmatter = Pluto.frontmatter(path)
+@info "Written by" frontmatter["author"]
+```