Repository navigation
v1.0.5 "Atlas"
First release of NerdGram1337. Atlas is the code name for the whole 1.x line. Diagrams are .mmd files on this computer. The app is a local, single-user tool: there is no account and no login.
Highlights
- A dashboard and an editor for Mermaid diagrams, with three sample diagrams the first time a data directory is empty.
- Delete moves a diagram or folder to trash. The last 20 revisions of a file are kept, and an autosave will not overwrite a copy that changed on disk.
- Move, duplicate, and import sit next to that. Search covers names and the text inside a diagram. Presentation is a full-screen, read-only view.
- Optional GitHub sync copies
.mmdfiles to a private repository you create with your own OAuth app. An in-app update check reads the public GitHub Releases for this project. - The same version is in
package.json, the About line, and the container imageghcr.io/networknerd1337/nerdgram1337:v1.0.5.
Security
The API listens on 127.0.0.1 and ::1 when HOST is unset. If IPv6 loopback is unavailable, IPv4 loopback still serves (#15).
- Every request needs an allowed
Host(localhost,127.0.0.1, or::1, plus any name inNERDGRAM_ALLOWED_HOSTS). Anything else is rejected. POST,PUT,PATCH, andDELETEhave to beContent-Type: application/json. A browser form cannot set that.- Those requests also check
OriginandSec-Fetch-Site. A page on another site is rejected.curlon this machine, which sends neither header, is allowed. HOST=0.0.0.0is for the container. The image sets it so Docker can publish the port, and the publish incompose.yamlis127.0.0.1:8787:8787. On the host, leaveHOSTunset.- Server and client tests run in CI.
Editing & files
Trash is a soft delete. Restore puts the file or folder back. Emptying trash is the permanent delete (#8).
- Each save keeps the previous contents. The last 20 revisions are kept, and you can restore one from the history dialog.
- Autosave sends the hash of the copy it loaded. If the file changed on disk, autosave pauses and asks you to keep yours unsaved, reload from disk, or overwrite with yours.
- An editor tab holds a lock on the open diagram so a second window does not write over it. The lock is not a login.
Move, duplicate, and import (#9):
- Move from the menu or by dragging onto a folder. A drop onto a diagram does nothing. A name that is already in the destination is not overwritten. Move to… can offer
Name (copy)when you need a free name. - Duplicate writes
Name (copy).mmd, thenName (copy 2).mmd. The copy is not favorited, does not take the source lock, and starts with no revision history. - Import reads
.mmd,.md, and.txt, up to 512 KB each, 25 files at a time, and 3 MB of text in one request. When a name is taken you choose Skip, Rename, or Replace. Replace goes through the normal save, so a locked file stays put and the previous bytes become a revision.
Diagrams & metadata
A diagram can start with Mermaid YAML front matter (#16).
title,config.theme,config.look, andconfig.layoutare Mermaid's own fields. Theme, look, and layout are also on the preview toolbar.- Description, tags, and notes live under
nerdgram:in that same block, so they stay in the.mmdfile and Mermaid ignores them. - Diagram info edits those fields in the editor.
- A legacy
%%{init}%%or%%{initialize}%%directive can be moved intoconfig. The directive's keys win where both set the same thing, which is how Mermaid already draws the diagram. Other front matter, includingnerdgram, stays.
Navigation & search
The dashboard keeps a thumbnail for each diagram under .meta/thumbs/ and reuses it while the file is unchanged (#10). The open tab also keeps an in-memory copy.
- Find and replace, and go to line, use the editor search keys. Go to line is Ctrl+Alt+G (Ctrl+Option+G on a Mac). On Windows, AltGr can collide with that chord. See Known limitations.
- Ctrl+K (Cmd+K on a Mac) opens the command palette from the dashboard, the editor, and the other pages. It stays closed during presentation.
Search matches the file name, the path, the title, tags, the description, notes, and the visible labels in the diagram, and ranks a name match ahead of a label buried in the source (#13). The dashboard field and the command palette use the same search. Names only limits it to file and folder names.
Presentation
Present opens the diagram full screen without saving it and without taking the editor lock (#18).
- Start with F5 or Ctrl+Shift+Enter (Cmd+Shift+Enter on a Mac) while a diagram is open and the cursor is not in a form field. F5 still reloads the page on the dashboard, the new-diagram page, and the reference. The command palette and the Present button on a card do the same thing.
- Esc leaves presentation. Zoom, pan, rotate, and fit are on the bar and on the keyboard. The bar hides until you move the pointer or press Tab.
- The view is read-only.
Templates
The template gallery ships six starters: flowchart, sequence, network topology, home lab, rack elevation, and firewall policy (#17). Creating a diagram copies the starter into your folder as a normal .mmd file. The gallery files live in templates/, not in the data directory. Dropping another .mmd file in that folder adds it to the gallery. This release does not store templates you save yourself.
GitHub sync
GitHub sync is optional (#14). NerdGram does not ship a client ID. You register an OAuth app in your own account, enable Device flow, and paste that client ID.
- The token is stored at
<data>/.meta/github-tokenwith mode0600, or taken fromNERDGRAM_GITHUB_TOKEN. It is not sent to the browser and not written into the git remote URL. - The git working copy is a hidden
.nerdgram-gitdirectory inside the data folder. The data directory itself is not a git repository. - Synced files are the
.mmddiagrams, plus a short README,.gitignore, and.gitattributesso the GitHub repository can be read on its own..meta, templates, and the syntax reference stay on this computer. - NerdGram does not force-push. If GitHub has commits this computer does not, you pull. When both copies changed, you choose Keep local, Keep both, or Use GitHub copy. An open editor is not overwritten.
Updates & releases
About and the bottom of the sidebar show the running version and its code name, for example v1.0.5 "Atlas". GET /api/version and GET /api/health return the same version, codename, commit when there is one, and how this copy was installed (#19).
- The update check calls the public GitHub Releases API for this repository. It sends no token and no telemetry. It reads the version from the release tag. The release title is not the version.
- When a newer stable release exists, the banner and the release dialog show that release's code name. The name comes from the major number (1 is Atlas, 2 is Meridian). A major that is not in the map is taken from a release title shaped like
vX.Y.Z "Name", and only when that title is that one safe phrase. - On a clean git clone of this repository, on
mainor a detached release tag, Update now fetches the tag and fast-forwards only (git merge --ff-onlyonmain). A tag that is not a fast-forward is refused. The check's "ahead" state meanspackage.jsonis newer than the latest stable tag. It is not a count of extra commits. - A Docker install is not changed from inside the container. About shows copyable pull, stop, remove, and run steps that keep the
nerdgram-datavolume and127.0.0.1:8787:8787. - The root
package.jsonversion is the only version.npm run version:synccopies it into the client, the server, the lockfiles, the Dockerfile, andcompose.yaml, and it copies the code name into the image build arg. Pushing thevX.Y.Ztag runs the release workflow and the image workflow.
Docker
The container image runs the production server as uid 1001, user nerdgram, with a read-only root filesystem in Compose (#12).
compose.yamlpublishes127.0.0.1:8787:8787and mounts the named volumenerdgram-dataat/data.- An empty
/datais seeded once from the image'sdiagrams/folder. The samples land at/data/Welcome.mmd,/data/NetworkMap.mmd, and/data/Examples/Sequence.mmd. A data directory that already has anything in it is left alone. - The image tag matches the package version:
ghcr.io/networknerd1337/nerdgram1337:v1.0.5. The workflow also pushes:latestandsha-<commit>when thev1.0.5tag is pushed. Pull requests do not push. - CI builds the image and runs a smoke test: health, a write, uid 1001, and a diagram that is still there after a restart.
- The image records the version and the code name.
org.opencontainers.image.versionis the version,org.opencontainers.image.codenameis the code name, andNERDGRAM_CODENAMEis set in the container environment. The running app still reads the code name frompackage.json.
Docs
The README is the install, security, and release-lifecycle guide (#11). Version numbers, the Atlas and Meridian code names, how to pin a release, and the steps to cut a tag are in Versioning and releases.
Known limitations
- There is no store of templates you save yourself. The gallery is the files in
templates/. - The editor preview has theme, look, layout, and Present. It does not zoom. Zoom, pan, and rotate are in presentation.
- On Windows, AltGr is reported as Ctrl+Alt. On a layout where AltGr+G types a character, Ctrl+Alt+G can type that character instead of opening Go to line. Use Go to line in the command palette.
- The first image on GHCR may still be private if the publish workflow cannot mark the package public. Set that package to Public once in the GitHub package settings.
What's Changed
- Add NerdGram1337 local Mermaid diagramming app by @NetworkNerd1337 in #1
- Add offline Mermaid syntax reference library (#4) by @NetworkNerd1337 in #5
- Add PDF export alongside SVG, PNG, and JPG (#2) by @NetworkNerd1337 in #6
- Add CodeMirror Mermaid syntax help in the editor (#3) by @NetworkNerd1337 in #7
- Bind the API to loopback and restrict Host and Origin by @NetworkNerd1337 in #20
- Add trash, version history, conflict-safe autosave, and editor locks by @NetworkNerd1337 in #21
- Add move UI, drag-and-drop, duplicate, and diagram import by @NetworkNerd1337 in #22
- Add Mermaid front matter for titles, themes, and notes by @NetworkNerd1337 in #23
- Add thumbnail cache, editor find, and a command palette by @NetworkNerd1337 in #24
- Search diagram text elements, not only file names by @NetworkNerd1337 in #25
- Add fullscreen presentation with zoom, pan, and rotate by @NetworkNerd1337 in #26
- Add a template gallery of bundled Mermaid starters by @NetworkNerd1337 in #27
- Add optional GitHub sync through a separate mirror by @NetworkNerd1337 in #28
- Add in-app update checks, git self-update, and a Docker upgrade walkthrough by @NetworkNerd1337 in #29
- Run NerdGram in Docker and publish the image to GHCR by @NetworkNerd1337 in #30
- Reorganize the README and document the release lifecycle by @NetworkNerd1337 in #31
- Prepare v1.0.5 "Atlas", the first release by @NetworkNerd1337 in #32
New Contributors
- @NetworkNerd1337 made their first contribution in #1
Full Changelog: https://github.com/NetworkNerd1337/NerdGram1337/commits/v1.0.5