# Project pack: linkding @ 27b7303

Facts about **linkding** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> linkding is a self-hosted bookmark manager that is easy to run and use. You save links with tags and notes, search them instantly, and keep archived copies of pages. There is a browser extension, a bookmarklet, an API, and import and export for common formats.

## Version and source
- Repository: https://github.com/sissbruecker/linkding
- Pinned commit: `27b7303baf41bb28babc610ac8eaa486e1ddfab5`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/sissbruecker/linkding/archive/27b7303baf41bb28babc610ac8eaa486e1ddfab5.zip
- Official docs: https://linkding.link
- Live demo: https://demo.linkding.link/login/. Shared demo. See the site for sign-in details. Don't enter real data.
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/sissbruecker/linkding bespoke-linkding
  cd bespoke-linkding
  git checkout --detach 27b7303baf41bb28babc610ac8eaa486e1ddfab5
  # Prepare development requirements and local configuration first.
  make init
  uv run manage.py createsuperuser --username=admin --email=admin@example.com
  make serve
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name linkding -p 9090:9090 -v linkding-data:/etc/linkding/data -e LD_SUPERUSER_NAME=admin -e LD_SUPERUSER_PASSWORD=choose-a-strong-password sissbruecker/linkding:latest
  # then open http://localhost:9090
  ```

- Needs: Docker for a trial, Python 3.12 with uv and Node for development
- Develop: `make serve`
- Test: `make test`
- Check/lint: `make lint`
- Stack: python, javascript (Django, Svelte, uWSGI). Difficulty for a non-developer with an AI: **easy**. A small Django app with a little Svelte. Clear structure and good tests. Most changes are a view, a template or a setting.

## Customisation points (settings → extend → code)
- **tags-and-bundles** [settings]: Organise links with tags and saved searches. → `In the app, under Bookmarks, Tags and Bundles`
- **general-settings** [settings]: Default view, archiving and sharing behaviour. → `Settings → General, Integrations`
- **rest-api** [extend]: Add and read bookmarks from scripts. → `Settings → Integrations and the API docs`
- **custom-css** [extend]: Restyle the interface without code. → `Settings → General → Custom CSS`
- **views-and-templates** [code]: New pages and layouts. → `bookmarks/templates and bookmarks/views`

## Must keep working
- Django migrations. Add new ones; never edit old ones.
- Authentication and API token checks.
- Import and export formats.

## Staying updatable
Prefer settings, custom CSS and the API. Small additions in new templates or views keep updates easy.

## Data, costs and safety
- Personal data: **yes**. Stored in: A SQLite database and saved assets under /etc/linkding/data. Bookmarks can reveal interests and plans. Back up the data folder.
- Service: Browser extension (optional, free): Save a page with one click.
- Setting `LD_SUPERUSER_NAME`: Name of the first admin user.
- Setting `LD_SUPERUSER_PASSWORD` (**secret**: the person enters it themselves, never in chat): Password of the first admin user. Never paste it into an AI chat.
- Use a strong admin password and HTTPS if it is reachable from the internet.
- Public sharing is off by default. Check before turning it on.

---

# Customising linkding

linkding is a compact Django project with a small amount of Svelte. The README explains the dev setup in a few commands.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Views and pages | bookmarks/views/ |
| Templates | bookmarks/templates/ |
| Models and migrations | bookmarks/models.py and bookmarks/migrations/ |
| REST API | bookmarks/api/ |
| Svelte components | bookmarks/frontend/ |
| Settings | bookmarks/settings/ |
| Documentation | docs/ |

## Use the gentlest change first

1. **Settings (no code):** tags, bundles, sharing and custom CSS.
2. **Extend:** the REST API and browser extension.
3. **Code:** new pages and fields.

## Recipes

- **New field on bookmarks:** add the model field and migration, include it in the form and API serializer, and show it in the list template.
- **New page:** add a view and template and link them from the navigation.

## Running and checking your changes

- `make test` runs unit tests and `make lint` the checks.
- Add a bookmark, tag it, search for it and export the list.

## Pitfalls

- Run `make frontend` after changing Svelte code.
- Keep the data folder out of Git.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/linkding/27b7303/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/linkding/27b7303/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/linkding/27b7303/r2/SKILL.md)