academic-project-astro-template: a research page built from Markdown

What the template replaces, and what it keeps

The template is described as a way to help you build a professional project page for your research paper, based on the design from the original Nerfies page. The sentence that explains the approach is the one about not manually editing an HTML file. You author the page's content in Markdown, you use a set of polished components, and you deploy it with GitHub Pages.

That is a small change in mechanism with a large change in what the author has to think about. The classic research project page is a single hand-written HTML file, and for a page with a hero image, a video, a comparison slider, a figure grid and a citation block, that file becomes a piece of unmaintainable markup that nobody wants to touch. Moving the content into Markdown means a contributor edits prose, and the layout comes from the template.

The design lineage is documented in the Credits section and it is three generations deep. The template was originally adapted from Eliahu Horwitz's Academic Project Page Template, which was itself adapted from Keunhong Park's project page for Nerfies. The licence is a Creative Commons Attribution-ShareAlike 4.0 International License.

The live demo is at research-template.roman.technology, and the README also lists a set of real pages built with it, from NVIDIA Research on token-efficient long video understanding, through MIT CSAIL's PolyPose on deformable 2D and 3D registration, to several ByteDance Seed pages on dexterous teleoperation, a Salesforce computer use benchmark and a robotics spatial understanding paper. That list is the best evidence of what the template is for, since a project page for a 3D vision or robotics paper is exactly the case that needs a video, a figure grid and a 3D object viewer.

The component set, and why each one is a component

The feature list is what distinguishes this from a generic Astro starter, and the components fall into groups.

There are pre-built components for LaTeX, figures, tables, code blocks with syntax highlighting, videos, YouTube embeds, 3D objects, comparison sliders, carousels, tabbed slides, and pairs of columns. The LaTeX support is the one that matters most for a research page, since a paper's equations are the reason the page exists at all. The comparison slider is the one that matters most for a 3D or vision paper, where the point is to let a reader drag between a method's output and a baseline's. Carousels and tabbed slides let a page show several results without scrolling forever, and pairs of columns are the layout a two-method comparison needs.

Three features are more about the pipeline than the components. Figures stored as PDF files are automatically converted into images, which removes the step where a researcher exports every figure twice. Images are compressed using AVIF and served as responsive images to minimise loading time. And font rendering is optimised with resized fallback font faces to prevent cumulative layout shift, which is the specific problem you get when a web font loads after the text is already laid out.

The remaining feature line is that the page is responsive, accessible, and SEO-optimised, and the last is that you can add your own components with HTML or any JavaScript framework you like. React comes pre-configured, but Vue, Svelte or others would work.

The 3D object support is worth a second look, because it changes the build. The dependency list includes @google/model-viewer, three, react-compare-slider and image-size, along with pdf-to-img for the figure conversion, which is a set of requirements you would not find in a blog starter.

The stack, and the build commands it exposes

The template is built with Astro, React, Tailwind, MDX and TypeScript, and the package.json shows the versions in use: Astro at 6.3.5, React at 19.2.1, TypeScript at 5.7.3, Tailwind CSS at 4.3.0 and the MDX integration at 5.0.4.

The scripts are the practical surface, and there are more of them than a typical site template because this one is meant to be worked in rather than just deployed.

  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro check && astro build",
    "preview": "astro preview",
    "astro": "astro",
    "check": "astro check",
    "lint": "eslint .",
    "lint:fix": "eslint --fix .",
    "format": "prettier .",
    "format:fix": "prettier --write .",
    "all:fix": "astro check && eslint --fix . && prettier --write ."
  },

Two of those are worth pointing at. The build script is not just astro build, it is astro check followed by astro build, so the type check runs as part of the production build and a type error blocks the deploy rather than surfacing afterwards. And the all:fix script chains the three tools in one command, which is the script a contributor runs before pushing.

The linting and formatting setup is correspondingly thorough, with ESLint 10 and plugins for React, CSS, JSON, Markdown and Astro, plus Prettier 3 with an Astro plugin and a Tailwind plugin, and eslint-plugin-better-tailwindcss available for class ordering. The top level of the repository carries eslint.config.ts, prettier.config.ts, tsconfig.json, astro.config.ts and a starwind.config.json.

Two more files at the root tell you what the project expects from you. bibliography.bib is the citation data, and it is processed by rehype-citation, which turns a BibTeX key into a formatted reference inside the prose. documentation.md is the reference the README points to for the component set.

Deploying to GitHub Pages, and the one configuration step

The deployment path is designed to need no configuration at all, and the README is explicit about that.

The first step is to use the template, which makes a copy of the repository in your own GitHub account. The second is to enable GitHub Pages for the repository, by going to the Settings tab and then to Pages under the Code and automation section, and using the dropdown to change Source from Deploy from a branch to GitHub Actions.

That dropdown is the whole configuration. The README says that at this point, whenever you push to the main branch, the GitHub Actions workflow in .github/workflows/astro.yml will automatically build a static website and deploy it to the URL of the form https://username.github.io/repository/. No other configuration is necessary.

The workflow file name in the repository listing is astro.yml, which tells you the build runs through the official Astro GitHub Action rather than a hand-rolled pipeline. The .github/ directory is the only one of its kind in the repository root, alongside the .vscode/ directory, .gitignore and .prettierignore.

For a user who does not want to run anything locally, the README points out a much shorter route. You could simply edit ./src/paper.mdx in your browser in the GitHub interface, without downloading or setting anything else up, and the workflow would rebuild the site from the change.

That file is the content. Everything about the page, the title, the authors, the abstract, the figures and the video, comes from src/paper.mdx, and the components in src/ are what render it.

The local editing loop, and the Node version it expects

The README recommends editing locally for faster preview, and the steps are short.

You clone the repository, install Node.js if you have not already, and make sure you are on version 24 or later, which you can check by running:

node --version

If your version is less than 24, the README points at the Node Version Manager and gives the command:

nvm install 24 && nvm use 24

Then, in the root directory of the cloned repository, you install the dependencies:

npm install

And start the development server:

npm run dev

The server runs at http://localhost:4321, and the README notes that the development server reloads automatically every time you save a file, so the loop is edit, save, look.

The last step is pushing your changes to the GitHub repository to trigger a new deployment. Alternatively, you can build the site locally and copy the output wherever you want to host it, and the build command creates a static website stored in the ./dist/ directory.

npm run build

Two details here are worth pausing on. The dev port is 4321, which is Astro's default, and the output directory is dist/, which is Astro's default too, so the template does not fight the framework's conventions. And the fact that the project requires Node 24 or later is a real constraint, since it is recent enough to rule out a lot of existing CI images, and the README gives you a version manager rather than telling you to upgrade your whole machine.

Note also that the package manager here is npm. The package-lock.json at the repository root confirms it, and the commands in the README use npm rather than pnpm or yarn.

Where this template is the wrong choice

Three cases point elsewhere. The first is a group that needs a different look. The README itself points to an alternative, Clarity, a minimalist website template for AI research by Shikun Liu, and says it has a beautiful and careful design distinct from the original Nerfies page, and that it is simply an HTML file styled with Sass. So the author is telling you that if the design is not what you want, do not spend a day fighting this one, because the underlying content structure of a research page is simple enough to hand-write in a single HTML file with a stylesheet.

The second is a project that needs anything server-side. This is a static site with a build step and a GitHub Pages deploy. There is no server component, no database, no search over past papers, no submission system, and no form handling beyond what static HTML can do. A group that wants a lab site with an index of every paper they have published, with the papers served from one place, needs a different project.

The third is a group that publishes a lot and does not want a static site per paper. Every repository is one page, and every page is a separate repository with its own workflow. That is the right shape for a single paper that is being announced once, and the wrong shape for a lab that maintains twenty of these.

The alternative worth comparing is the plain HTML approach the README itself describes, and the difference in approach is instructive. Writing the page as one HTML file with Sass, as Clarity does, means no build step, no Node version requirement, no npm install, and nothing to keep in sync when the framework moves. What you give up is the component set, the automatic figure conversion, the LaTeX rendering, the comparison slider, the 3D viewer and the GitHub Actions deploy, all of which are the reasons to use this template rather than a single file. If your page is a hero image, an abstract, a video and a citation, a single HTML file is a fraction of the work. If your page has twelve figures, a comparison slider, a 3D object and a BibTeX citation list, this template turns a day of layout into an afternoon of writing.

Editorial conclusion

The template fits a researcher or lab that wants a polished project page in an afternoon without touching HTML, especially for a paper with figures, a video and a 3D viewer. It does not fit a lab that needs a custom backend, a CMS, or a page that must live outside GitHub Pages without extra work, and it does not fit a group that wants a different look, since the design is deliberately the Nerfies one. Before you start, read documentation.md, because it is the reference for the component set, and check that your figures are either raster images or PDFs, since the PDF-to-image conversion is automatic but the other formats are not.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. RomanHauksson/academic-project-astro-template on GitHub