minimalist-portfolio-json and the case for a portfolio site driven by one file

One JSON file replaces the page templates

minimalist-portfolio-json is a portfolio template built with Astro whose entire content layer is a single file. The project describes itself as a minimalist portfolio configurable via one JSON, and the README frames it as a minimalist CV laid out for web and PDF.

The JSON follows the schema published at jsonresume.org, which is the decision that makes this template reusable rather than personal. A CV file written for that schema is not tied to this particular design, so a person who later wants a different layout can carry the same data elsewhere. The README states that the design is based on the work of BartoszJarocki, which explains where the typography and the sparse layout come from without asking the user to invent them.

The audience is narrow and obvious: developers, designers and other independent professionals who need a small site that shows a CV, is easy to print, and can be thrown on a static host. The homepage is a Vercel deployment, and the primary language is Astro.

The licence is MIT, in a file called LICENSE.txt, and the repository is not archived. The last push was on 2026-10-16, and the project has no GitHub releases, so there is no versioned history to read and the only upgrade path is the template itself.

Astro static output, a command palette and a locally served font

The stack section of the README names four pieces. Astro is the web framework, TypeScript supplies the typing, HotKeyPad provides a command palette with keyboard shortcuts written in plain JavaScript, and Mona Sans is used as a variable font.

The font detail is the one with a real engineering consequence. Mona Sans is served locally rather than pulled from a font CDN, and it is subset, with the files kept in src/assets/fonts. That means the repository carries font binaries and the build has to subset them, and it also means the site does not depend on a third party being reachable at request time, which matters for a site that is partly a PDF.

The dependency list is short. package.json pins astro at 7.4.0 and hotkeypad at 1.0.2 as runtime dependencies, with @astrojs/check at 0.9.10 and typescript at 6.0.3 as dev dependencies. The package is an ES module and its version is 0.0.1, which for a template is a fair signal that the schema is the stable contract rather than the package version.

The build script is worth reading because it shows where quality control happens. The build command runs astro check and then astro build, so type errors are surfaced during the build rather than only in the editor. The dev and start commands both run astro dev, and preview runs astro preview.

Starting from the template and editing cv.json

The setup path is a template instantiation, not a clone, so the upstream repository stays clean and you get a fresh project of your own. You need Node.js 22.22 or newer according to the README, and pnpm as the package manager.

# Instala pnpm
npm install -g pnpm

# Inicializa el proyecto
pnpm create astro@latest -- --template midudev/minimalist-portfolio-json

The second command pulls the template into a new Astro project, and the template argument is the GitHub repository path.

After that, the content step is editing one file. The README says to edit cv.json to create your own printable portfolio or CV, and the schema is the jsonresume.org one, so the fields are the familiar ones for anyone who has seen that format.

The development server is the last step.

# Disfruta del resultado
pnpm dev

The dev or start command starts a local server on localhost:4321, which is where you open the browser to see the result. The build command checks for possible errors and produces a production bundle in ./dist, and preview gives a local view of that build, also on localhost:4321. The output of build is a plain static directory, so deployment is whatever static host you already use.

Two languages means two JSON files and two config edits

The portfolio is generated in Spanish at the root path and in English at /en, and the English version comes from a separate file, cv_english.json. The routing and the mapping live in src/i18n/index.ts, and the interface strings live in src/i18n/ui.ts.

The README documents the two edits you are likely to want. To ship a single language, remove en from the LANGUAGES list along with its import and delete cv_english.json, and the language selector disappears. To add a language, create its own JSON file, for example cv_french.json, import it in LANGUAGES, and add its interface texts in ui.ts.

That is a fair amount of ceremony for one more language, and it is the first thing that makes the template feel less like one file than the description suggests. Adding a language touches the data file, the language map and the interface strings, and the README gives no guidance on translating the interface text itself beyond adding entries to ui.ts.

The top level of the repository is small and matches that design: cv.json, cv_english.json, astro.config.mjs, package.json, pnpm-lock.yaml, tsconfig.json, and directories for src, public, and .vscode. The absence of a separate content directory is the point of the whole exercise.

The Node version requirement is stated two different ways

There is a discrepancy worth catching before you start. The README tells you that you need Node.js 22.22 or superior. The package.json engines field asks for something stricter.

"engines": {
    "node": "24.x"
  }

So the documented floor and the enforced floor are not the same. A developer on Node 22 who follows the README will hit an engine complaint from the package manager on install, and the fix is either to move to Node 24 or to work around the engine check. The README does not mention the engines field at all, and the discrepancy is not documented anywhere in the repository.

The second limitation is quieter. The README describes the project as a CV laid out for web and PDF, but the commands table lists only dev, build and preview. There is no print-to-PDF script, no PDF export step and no headless browser configuration in the documented commands, so the PDF side of the promise appears to rely on the browser's own print function rather than on a build artifact. If your requirement is a generated PDF file you can email or attach, that assumption needs checking before you commit.

The third is the absence of releases. The repository has no GitHub releases, and the README has no changelog or upgrade notes. Template updates arrive by re-running the template command or by pulling upstream, and a fork that has diverged has no documented way to reconcile.

Against a hand-written HTML CV, the difference is where the content lives

The realistic alternative to this template is a hand-written static HTML or Markdown CV that you style yourself, hosted on any static host and printed from the browser. The difference in approach is narrow but decisive.

A hand-written CV puts the content and the presentation in the same place. Changing a job title means finding the right line in a component or a stylesheet, and adding a section means writing markup. The tradeoff is control: you own every pixel, every font and every breakpoint, and you can do things no schema anticipates.

This template inverts that. The content sits in a JSON file that follows an external schema, and the presentation is fixed and already designed, with a printed layout and a bilingual structure. The tradeoff is that anything the schema cannot express has to be worked around, and anything about the visual design has to be accepted or overridden in CSS. For most individual professionals that is the right way round, since a CV has a recognisable structure and the design is not the hard part. For someone with unusual content, a bespoke layout or a strong opinion about typography, it is the wrong way round.

The two are also cheap to try side by side, since a fork of the template and a single HTML file cost nothing to compare. The deciding factor is not the layout, it is whether you want your CV content in a portable schema or in markup you control.

Editorial conclusion

This template fits an individual developer who wants a printable web portfolio and a PDF-ready CV in two languages and does not want to maintain page templates, because all content lives in cv.json and cv_english.json and the design work is already done. It does not fit teams that need a CMS, multi-author editing, or a deployment target other than a static build, and it does not fit anyone who cannot accept that adding a language means editing src/i18n/index.ts and src/i18n/ui.ts as well as adding a JSON file. Verify first that your Node version satisfies the engines field in package.json, which asks for 24.x while the README asks for 22.22 or newer, and check that the printed output still suits you before you point a domain at it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. midudev/minimalist-portfolio-json on GitHub
4. Project website
5. README