research-portal
Skill4 starsChanged 20 days agoMITView on GitHub
Build and manage a local MkDocs Material "research portal" over a folder of Typora/markdown research notes (e.g. ~/notes or a Dropbox-synced folder), keeping the original .md files untouched. Use this whenever the user wants to collect, browse, organize, or curate a folder of dated markdown notes into a searchable navigable site; wants a lighter local alternative to Obsidian / Notion / Outline / Logseq for their own notes; needs perfect LaTeX/math rendering in a notes site; wants notes grouped by project in a sidebar; or wants to tag/rename notes by project without breaking image links. Trigger even if they don't say "MkDocs" or "portal" but describe wanting to "정리해서 모아 보기", make a personal wiki, or render math from their note folder.
In this repository38 other files it gives its agents.
- academic-cvSkill
- academic-jobsSkill
- academic-proseSkill
- adversarial-reviewSkill
- bibtex-genSkill
- chrome-sessionSkill
- clickup-cliSkill
- clickup-todaySkill
- commit-triageSkill
- concept-explainerSkill
- contact-emailSkill
- cover-letterSkill
- dropboxSkill
- handdrawn-schematicSkill
- hep-rumor-millSkill
- journal-club-reviewSkill
- magi-researchSkill
- md2pdf-typoraSkill
- morgenSkill
- overleaf-section-workflowSkill
- overleapSkill
- peer-agent-reviewSkill
- proton-mailSkill
- reference-searchSkill
- remarkable-syncSkill
- research-backupSkill
- research-boardSkill
- research-logSkill
- research-proposalSkill
- research-reportSkill
- research-statementSkill
- scienceplot-pySkill
- vastaiSkill
- wide-slide-illustratorSkill
- workshop-paper-reviewSkill
- xkcd-pySkill
- zai-web-searchSkill
- zoom-summarySkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 38
Only three helper files land in the notes folder, all regenerable/deletable: index.md (home), SUMMARY.md (sidebar nav), …
- Very specific: line 49
All commands run from the portal dir with uv.
- Distinctive: line 55
Ask for the notes folder if not given.
- Distinctive: line 75
Run it in the background so you can keep working.
- Very specific: line 113
After scaffold/build: uv run mkdocs build exits 0 (the red "MkDocs 2.0" notice from Material is harmless).
- Very specific: line 116
After tagging: the script's own link verification must report "all asset refs resolve OK".
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Research Portal
Turn a folder of dated markdown notes into a local, searchable MkDocs Material
site with project-grouped navigation and full LaTeX rendering, without ever
modifying the source notes. The site is read/browse oriented; authoring stays in
the user's existing editor (Typora), so the .md files remain the canonical
source.
When this fits (and when it doesn't)
This is the right tool when notes are flat markdown files in a folder (often
Dropbox-synced), named by date like YYYYMMDD[_PROJECT].md, with images in
sibling <stem>.assets/ folders. It deliberately avoids database-backed wikis
(Outline needs Postgres/Redis/SSO; Notion is a SaaS DB) because those divorce
content from the user's files and break the Typora workflow. If the user instead
wants backlink/graph visualization, mention Quartz as a complement; this skill
does not do graphs.
Design choices (read references/design.md for the why)
docs_dirpoints straight at the notes folder. The site serves.md,.assets/images, and PDFs in place; originals are never touched.- Only three helper files land in the notes folder, all regenerable/deletable:
index.md(home),SUMMARY.md(sidebar nav),javascripts/mathjax.js. - Math:
pymdownx.arithmatex(generic) protects inline$...$from markdown, and MathJax 3 also scans raw$$...$$as a fallback because arithmatex's block processor does not descend into list items (Typora notes often nest display math under bullets). This combination renders both reliably. - Broken symlinks in the source abort an mkdocs build, so the scaffolder auto-excludes any first-level subtree that contains dangling links.
Workflow
All commands run from the portal dir with uv. Scripts are bundled in
scripts/; the scaffolder copies gen_index.py and tag_note.py into the
portal dir so the portal is self-contained.
1. Scaffold
Ask for the notes folder if not given. Then:
python <skill>/scripts/scaffold.py \
--notes-dir ~/notes \
--portal-dir ~/research-portal \
--name "Research Portal" --lang ko --port 8123This writes mkdocs.yml, copies the helper scripts, writes the MathJax config,
detects broken-symlink subtrees to exclude, then creates the uv venv, installs
mkdocs-material + mkdocs-literate-nav, and builds the nav. Pass --no-install
to only generate files (it then prints the uv commands to run).
2. Serve
cd ~/research-portal && uv run mkdocs serve -a 127.0.0.1:8123Run it in the background so you can keep working; it live-reloads when notes or config change. After installing a new plugin, restart serve (a running process won't see newly installed packages). Tell the user the URL and suggest a hard refresh (Ctrl+Shift+R) after JS/config changes.
3. Regenerate nav after adding/removing notes
cd ~/research-portal && uv run python gen_index.py --title "Research Portal"gen_index.py parses YYYYMMDD[_PROJECT[_extra]].md, groups by project (most
notes first, untagged "Daily" last), labels each entry by date, and writes
index.md + SUMMARY.md. It reads the notes dir from docs_dir in mkdocs.yml.
4. Tag / rename notes by project
Untagged date-only notes show up under "Daily". To file them under a project,
first read enough of each note to classify it (section headers grep -E '^#{2,3} '
are a fast topic fingerprint). For genuinely multi-project notes, ask the user
rather than guessing. Then:
cd ~/research-portal
# preview first
uv run python tag_note.py --project ProjectA 20240115 20240116 --dry-run
# apply
uv run python tag_note.py --project ProjectA 20240115 20240116tag_note.py renames <stem>.md, the <stem>.assets/ folder, and a matching
<stem>.pdf, and rewrites every <stem>.assets reference across ALL notes
(image references can be cross-file). It then verifies all *.assets references
resolve. Use --rename OLD NEW for an explicit single rename (e.g. re-tagging an
already-suffixed note). Always run gen_index.py afterward to refresh the nav.
Verify before reporting done
- After scaffold/build:
uv run mkdocs buildexits 0 (the red "MkDocs 2.0" notice from Material is harmless). Confirm math by grepping the built page forclass="arithmatex"and that*.assets/images copied intosite/. - After tagging: the script's own link verification must report "all asset refs
resolve OK"; also confirm no date-only notes remain if the intent was to clear
"Daily" (
ls <notes> | grep -E '^[0-9]{8}\.md$').
Scripts and references
scripts/scaffold.py— create/refresh the portal project and uv envscripts/gen_index.py— regenerateindex.md+SUMMARY.mdscripts/tag_note.py— safe project tagging/renaming with link repairreferences/design.md— rationale for the math config, file layout, and the Outline/Obsidian comparison; read it if the user questions a design decision or wants to adapt the setup (different filename scheme, KaTeX, hosting, etc.).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

