Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/academicpages/academicpages.github.io/llms.txt

Use this file to discover all available pages before exploring further.

The talks generator converts a tab-separated or comma-separated spreadsheet of your presentations into individual .md files in the _talks/ directory. Each file contains Jekyll front matter that Academic Pages uses to render your Talks listing, individual talk pages, and the talks section of your CV. After generating talk files you can optionally run a second tool — talkmap.py — to produce an interactive Leaflet cluster map of every location where you have presented.

​
Input file format

The generator reads a .tsv or .csv file. The file must begin with a header row. The template ships with markdown_generator/talks.tsv as a starting point.

​
Column reference

ColumnRequiredNotes
titleYesTitle of the talk or tutorial
typeNoPresentation type, e.g. Talk, Tutorial, Conference proceedings talk. Defaults to Talk if the value is 3 characters or fewer
url_slugYesSlug used in the filename and permalink, e.g. talk-1
venueNoName of the venue, department, or conference
dateYesDate in YYYY-MM-DD format
locationNoHuman-readable location string, e.g. San Francisco, California. Used by the talkmap geocoder
talk_urlNoURL with more information about the talk; generates a “More information here” link in the page body
descriptionNoFreeform description or abstract for the talk
title, url_slug, and date are the only required fields. Rows missing any of these three are skipped with a warning printed to stderr.

​
Example TSV content

The template’s talks.tsv contains four sample rows. Here is an excerpt showing two of them (columns separated by tabs): 
title	type	url_slug	venue	date	location	talk_url	description
Talk 1 on Relevant Topic in Your Field	Talk	talk-1	UC San Francisco, Department of Testing	2012-03-01	San Francisco, California		This is a description of your talk, which is a markdown files that can be all markdown-ified like any other post. Yay markdown!
Tutorial 1 on Relevant Topic in Your Field	Tutorial	tutorial-1	UC-Berkeley Institute for Testing Science	2013-03-01	Berkeley CA, USA	http://exampleurl.com	This is a description of your tutorial, note the different field in type. This is a markdown files that can be all markdown-ified like any other post. Yay markdown!

​
Running the generator

2
cd markdown_generator
3
Run the script with your input file
4
Pass the TSV or CSV filename as the first argument. An optional second argument sets the output directory (defaults to ../_talks/):
5
TSV input
python3 talks.py talks.tsv
CSV input
python3 talks.py talks.csv
Custom output directory
python3 talks.py talks.tsv /path/to/custom/_talks/
6
The script detects the delimiter automatically from the file extension (.tsv/.txt → tab, anything else → comma).
7
Confirm the output files
8
The generator creates one file per row in ../_talks/, named YYYY-MM-DD-[url_slug].md. Check the output:
9
ls ../_talks/
10
Each file is also confirmed with a Created: <path> message in the terminal.

​
Generated output

For the first sample row in talks.tsv, the generator produces _talks/2012-03-01-talk-1.md: 
---
title: "Talk 1 on Relevant Topic in Your Field"
collection: talks
type: "Talk"
permalink: /talks/2012-03-01-talk-1
venue: "UC San Francisco, Department of Testing"
date: 2012-03-01
location: "San Francisco, California"
---

This is a description of your talk, which is a markdown files that can be all markdown-ified like any other post. Yay markdown!
For the second row, which includes a talk_url, the body also gains a link: 
---
title: "Tutorial 1 on Relevant Topic in Your Field"
collection: talks
type: "Tutorial"
permalink: /talks/2013-03-01-tutorial-1
venue: "UC-Berkeley Institute for Testing Science"
date: 2013-03-01
location: "Berkeley CA, USA"
---

[More information here](http://exampleurl.com)

This is a description of your tutorial, note the different field in type. This is a markdown files that can be all markdown-ified like any other post. Yay markdown!
Key points about the generated front matter:
  • collection: talks is always set.
  • type defaults to "Talk" when the column value is 3 characters or fewer.
  • permalink is constructed as /talks/YYYY-MM-DD-[url_slug].
  • venue and location fields are only written when the column values are non-empty.
  • Ampersands, single quotes, and double quotes in description are HTML-escaped in the page body.

​
Jupyter notebook alternative

talks.ipynb provides the same generation logic in an interactive Jupyter notebook with additional inline documentation. 
# From the markdown_generator/ directory
jupyter notebook talks.ipynb
Run all cells in sequence. The notebook reads talks.tsv by default and writes to ../_talks/.

​
Generating the talkmap

After your _talks/ directory is populated, you can generate an interactive Leaflet cluster map of every location where you have given a talk. This step uses a separate script at the repository root.
1
Install the required packages
2
talkmap.py depends on frontmatter, geopy, and getorg, which are not part of the Python standard library.
3
pip install python-frontmatter geopy getorg
4
Run talkmap.py from the repository root
5
# From the repository root (not from markdown_generator/)
python3 talkmap.py
6
The script reads every .md file in _talks/, extracts the location front matter field, geocodes each location using the Nominatim service, and writes the results to talkmap/map.html and talkmap/org-locations.js.
7
Enable the map link in _config.yml
8
By default the Talks page does not show a link to the map. Set talkmap_link to true to display it:
9
# _config.yml
talkmap_link: true   # change to true to add link to talkmap on talks page
10
With this option enabled, the Talks page renders: “See a map of all the places I’ve given a talk!” linking to /talkmap.html.
11
Commit the talkmap output
12
Add the generated files to version control and push:
13
git add talkmap/
git commit -m "Regenerate talkmap"
git push
The talkmap geocodes locations by sending them to the Nominatim API. Each geocoding request is subject to a 5-second timeout. Talks with a missing location field are silently skipped. If geocoding fails (timeout or unrecognised place name), the error is printed to stdout but the script continues processing remaining talks.

​
Automated talkmap with GitHub Actions

The repository includes .github/workflows/scrape_talks.yml, which automatically regenerates the talkmap whenever files in talks/, _talks/, or talkmap.ipynb are pushed to the repository. 
name: Scrape Talk Locations

on:
  push:
    paths:
      - 'talks/**'
      - '_talks/**'
      - 'talkmap.ipynb'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
    - uses: actions/checkout@v2

    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.9'

    - name: Install dependencies
      run: |
        pip install jupyter pandas requests beautifulsoup4 geopy
        pip install getorg --upgrade

    - name: Run Jupyter Notebook
      run: |
        jupyter nbconvert --to notebook --execute talkmap.ipynb --output talkmap_out.ipynb

    - name: Commit changes
      run: |
        git config user.name "github-actions[bot]"
        git config user.email "github-actions[bot]@users.noreply.github.com"
        git add .
        git commit -m "Automated update of talk locations" || echo "No changes to commit"
        git push
The workflow executes talkmap.ipynb (not talkmap.py) via jupyter nbconvert and commits the updated talkmap/ output back to the repository. The contents: write permission is required for the commit step.
The workflow only runs when files matching the paths filter change. If you update talk files frequently, the talkmap will stay current automatically. If you prefer to regenerate it manually, you can delete or disable this workflow — the generated talkmap/ files are static and remain valid until your talk locations change.

Build docs developers (and LLMs) love

Get started for freeTalk to us