Lepton Documentation

Configuration Copy Section

Configuration

Lepton reads user configuration from a .leptonrc JSON file in the home directory reported by Electron. In Lepton v1.9.0 and later, the exact path is shown on the About page (Command/Ctrl + ,).

The file is not generated automatically. Create it if you want to override the defaults below.

Template `.leptonrc` Copy Chapter

{
  "theme": "light",
  "autoUpdate": false,
  "startAtLogin": false,
  "i18n": {
    "locale": "en"
  },
  "window": {
    "closeToTray": false,
    "minimizeToTray": false
  },
  "avatar": {
    "type": "github",
    "boringAvatarVariant": "beam"
  },
  "userPanel": {
    "hideProfilePhoto": false
  },
  "logger": {
    "level": "info"
  },
  "security": {
    "cachedAccessTokenStorage": "auto"
  },
  "proxy": {
    "enable": false,
    "address": "socks://localhost:1080"
  },
  "snippet": {
    "sorting": "updated_at",
    "sortingReverse": true,
    "expanded": true,
    "newSnippetPrivate": false,
    "downloadAll": false
  },
  "tag": {
    "showInSnippetList": false,
    "colored": false
  },
  "editor": {
    "tabSize": 4,
    "validateFilename": true
  },
  "enterprise": {
    "enable": false,
    "host": "",
    "token": "",
    "avatarUrl": ""
  },
  "notifications": {
    "success": true,
    "failure": true
  },
  "zoom": {
    "percent": 100
  },
  "shortcuts": {
    "keyShortcutForSearch": "Shift+Space",
    "keyNewGist": "CommandOrControl+N",
    "keyEditGist": "CommandOrControl+E",
    "keyDeleteGist": "CommandOrControl+Delete",
    "keySubmitGist": "CommandOrControl+S",
    "keyImmersiveMode": "CommandOrControl+I",
    "keyAboutPage": "CommandOrControl+,",
    "keyDashboard": "CommandOrControl+D",
    "keySyncGists": "CommandOrControl+R"
  }
}

Options Copy Chapter

Debug Logging Copy Chapter

Set logger.level to debug when collecting logs for an issue report:

{
  "logger": {
    "level": "debug"
  }
}

Home Directory Notes Copy Chapter

macOS Copy Section

On macOS, the home directory is your user folder under /Users. Place .leptonrc here:

/Users/<CurrentUserName>/.leptonrc

In Finder, use Go > Home to open the home directory. Because .leptonrc starts with a dot, it is hidden by default; press Command + Shift + . to show hidden files.

Windows Copy Section

The home directory can vary by Windows distribution, but it usually starts here:

C:\Users\<CurrentUserName>\.leptonrc

Use the About page (Command/Ctrl + ,) to find the exact path.

Linux Snap Package Copy Section

For the snap package, Electron may report ~/snap/lepton/current as the home directory instead of ~. Use the About page (Command/Ctrl + ,) to find the exact path.

Questions Or Issues Copy Chapter

Open issues and feature requests at https://github.com/hackjutsu/Lepton/issues.

Faq Copy Section

FAQ

Why Is The Language Of My Snippet "Other"? Copy Chapter

Lepton depends on GitHub's API to detect snippet language. If GitHub cannot classify the language, Lepton marks it as Other.

You can add a Vim modeline at the top of the snippet to give GitHub a language hint:

// vim: syntax=javascript
let test = 'This is a javascript file'

Search Copy Chapter

The default search shortcut is Shift + Space.

Lepton can search these fields:

• filename
• language
• description
• tag
• snippet id
• downloaded snippet file content

Complete global content search across every snippet requires the
snippet.downloadAll option to be enabled before syncing. When downloadAll is
disabled, content search only covers snippets whose details and file content have
already been downloaded locally, such as snippets opened during the session.

See Configuration for the snippet.downloadAll option.

Title And Tags Copy Chapter

Use this pattern in the snippet description to set a title and custom tags:

[title] description #tag1 #tag2

Legacy tag syntax is also supported:

[title] description #tags: tag1, tag2

What Is `.leptonrc`, And Where Should I Put It? Copy Chapter

.leptonrc is Lepton's user configuration file. It is parsed when the app starts and is not created automatically.

Create .leptonrc in the home directory reported by Electron. In Lepton v1.9.0 and later, the exact path is shown on the About page (Command/Ctrl + ,).

See Configuration for the current template and option list.

How Do I Add A New Interface Locale? Copy Chapter

Adding a locale touches both the renderer catalog and the packaged Electron
locale resources:

1. Add app/utilities/i18n/locales/<locale>.js, using en.js as the complete
   key reference.
2. Import the catalog in app/utilities/i18n/index.js, add it to catalogs,
   and add the display name to supportedLocales.
3. Update tests/utilities/i18n.test.js so the new catalog is checked for key
   shape, translated values, and package-locale coverage.
4. Update the supported i18n.locale lists in README.md and
   wiki/configuration.md.
5. Update configs/electronLanguages.js if the new Lepton locale needs a
   different Electron/Chromium resource name in packaged apps.
   electron-builder.js derives the packaged locale list from
   getSupportedLocales(), so do not add a separate hard-coded list to
   package.json.
6. Validate with npm run test:unit and npm run test:packaged-smoke. For
   packaged builds, confirm every Lepton-supported locale is present and
   intentionally unsupported Electron locales are absent.

Proxy Copy Chapter

Put proxy settings in .leptonrc:

{
  "proxy": {
    "enable": true,
    "address": "socks://localhost:1080"
  }
}

See Configuration for all proxy-related options.

Enable GitHub Enterprise Copy Chapter

Create a GitHub personal access token with the gist scope enabled. Then add your GitHub Enterprise host and token to .leptonrc:

{
  "enterprise": {
    "enable": true,
    "host": "github.example.com",
    "token": "token_with_gist_scope",
    "avatarUrl": ""
  }
}

See Configuration for the full enterprise option list.

Scope For GitHub Access Token Copy Chapter

Lepton can use token login instead of GitHub OAuth credentials. Create a
GitHub personal access token with the gist scope, then paste that token into
Lepton's token login screen.

The fastest path is GitHub's prefilled token page:
Create a Lepton token with the gist scope.

If you create the token manually:

1. Open GitHub, then go to Settings -> Developer settings -> Personal access
   tokens -> Tokens (classic).
2. Select Generate new token -> Generate new token (classic).
3. Enter a descriptive note, such as Lepton, and choose an expiration.
4. Under Select scopes, enable only gist.
5. Click Generate token and copy the token immediately. GitHub only shows it
   once.

For GitHub Enterprise, create the token on your Enterprise host with the same
gist scope.

About Data Collection Copy Chapter

Lepton is a desktop snippet client backed by GitHub Gist and does not run its own sync service. Data is stored locally by the app or remotely in GitHub Gist.

Donation Copy Chapter

Lepton does not accept personal donations. If you want to donate, consider donating to the Wikimedia Foundation, which helps sustain free knowledge through Wikipedia and related projects.

You are welcome to create an issue to share how much you contributed.

Publish Flow Copy Section

Publish Flow

Lepton publishes desktop builds through the Release GitHub Actions workflow.
Merging release-flow changes does not publish anything by itself. Publishing
starts only when a version tag is pushed or when the workflow is run manually.

Release Types Copy Chapter

Stable tags must be plain semver tags:

git tag v1.10.2
git push origin v1.10.2

Prerelease tags must include a semver prerelease suffix:

git tag v1.11.0-alpha.1
git push origin v1.11.0-alpha.1

git tag v1.11.0-beta.1
git push origin v1.11.0-beta.1

git tag v1.11.0-rc.1
git push origin v1.11.0-rc.1

The workflow rejects tags that do not look like v1.2.3 or
v1.2.3-beta.1.

Required Secrets Copy Chapter

Configure these in GitHub Actions secrets before publishing:

The workflow uses GitHub's built-in GITHUB_TOKEN for GitHub Release uploads.

configs/account.js is not committed. Each release job generates it from
LEPTON_GITHUB_CLIENT_ID and LEPTON_GITHUB_CLIENT_SECRET before packaging so
release artifacts use the configured GitHub OAuth app.

Use GitHub Environments if prerelease and production should have different
secret values or approval rules.

Stable Release Flow Copy Chapter

Use this flow for versions intended for all users.

merge release-ready code to master
    |
    v
create plain semver tag, for example v1.10.2
    |
    v
push tag to origin
    |
    v
Release workflow
    |
    +--> resolve context:
    |       publish_policy=always
    |       github_release_type=release
    |       environment=production
    |       snap_channels=stable
    |
    +--> validate:
    |       npm run lint
    |       npm run test:unit
    |       npm run test:build
    |
    +--> build macOS:
    |       dmg + zip for x64
    |       dmg + zip for arm64
    |       ad-hoc signed, not notarized
    |
    +--> build Windows:
    |       NSIS installer for x64 and ia32
    |       7z archive for x64 and ia32
    |       unsigned by policy
    |
    +--> build Linux:
    |       AppImage for x64
    |       snap for x64
    |
    v
publish GitHub Release and release assets
    |
    v
publish Snap to stable channel
    |
    v
stable auto-update metadata is available

The macOS job builds Intel and Apple Silicon artifacts in one electron-builder
run so latest-mac.yml is generated once for the full macOS artifact set.

macOS Gatekeeper And Windows SmartScreen Copy Chapter

Lepton does not require paid Apple Developer Program or Windows code-signing
certificates for publishing. macOS artifacts are ad-hoc signed so the app
bundle is structurally valid for local code-signing checks, but they are not
Developer ID signed or notarized. The workflow does not read Apple certificate
secrets.

Expected user-facing behavior:

• macOS users should expect Gatekeeper to say Apple cannot verify Lepton is
  free of malware. They may need to open Lepton from Finder's context menu or
  approve it in Privacy & Security settings.
• If macOS still reports that Lepton is damaged after the app is dragged into
  /Applications, advanced users can clear the downloaded-app quarantine flag:
  xattr -dr com.apple.quarantine /Applications/Lepton.app.
• Windows users should expect Microsoft Defender SmartScreen warnings until the
  unsigned app has enough reputation.
• macOS and Windows auto-update metadata is still published for stable tags,
  but ad-hoc-signed macOS updates and unsigned Windows updates should be
  manually verified before they are advertised as fully supported update paths.

If Developer ID signing or notarization is added later, update
.github/workflows/release.yml, electron-builder.js, this wiki page, and the
README together.

Stable app builds are eligible to check for updates when the user's
.leptonrc has:

{
  "autoUpdate": true
}

Only newer stable versions should notify users. Prerelease candidates are
ignored by the updater policy.

Prerelease Flow Copy Chapter

Use this flow for testing builds that should be public but should not notify
stable users.

merge prerelease-ready code to master
    |
    v
create semver prerelease tag, for example v1.11.0-beta.1
    |
    v
push tag to origin
    |
    v
Release workflow
    |
    +--> resolve context:
    |       publish_policy=always
    |       github_release_type=prerelease
    |       environment=prerelease
    |       snap_channels=edge
    |
    +--> validate:
    |       npm run lint
    |       npm run test:unit
    |       npm run test:build
    |
    +--> build macOS, Windows, and Linux artifacts
    |
    v
publish GitHub prerelease and prerelease assets
    |
    v
publish Snap to edge channel
    |
    v
no stable-user auto-update notification

Prerelease app versions do not check for updates. Stable app versions also do
not notify for prerelease update candidates.

Manual Release Workflow Runs Copy Chapter

The workflow can be started manually from the GitHub Actions UI.

Manual inputs:

Manual runs default to publish=never, so they build artifacts and upload
workflow artifacts without creating a GitHub Release or publishing to the Snap
Store.

Expected Artifacts Copy Chapter

Artifact names include product name, version, operating system, architecture,
and extension:

Lepton-1.10.2-mac-x64.dmg
Lepton-1.10.2-mac-arm64.zip
Lepton-1.10.2-win-x64.exe
Lepton-1.10.2-win-ia32.7z
Lepton-1.10.2-linux-x64.AppImage
Lepton-1.10.2-linux-x64.snap

Updater metadata files such as latest.yml and latest-mac.yml are also
generated and published with GitHub release assets.

Failure Handling Copy Chapter

If validation fails, fix the branch and create a new tag after the fix is
merged. Do not reuse a published version tag unless the failed workflow did not
publish any artifacts.

If publishing partially succeeds:

1. Remove or repair the incomplete GitHub Release assets.
2. Remove incorrect Snap channel revisions or close the affected channel in the
   Snap Store.
3. Create a new patch or prerelease tag.
4. Run the release flow again from the new tag.

Avoid force-moving public release tags after users may have downloaded assets.

Local Packaging Fallback Copy Chapter

Local packaging is still available for diagnosing build issues:

npm ci
npm run dist -- -m
npm run dist -- -w
npm run dist -- -l

Local release-like packaging still needs configs/account.js to exist. The
GitHub Actions workflow generates this file from secrets; local builds must
create it manually.

README Copy Section

Lepton Wiki

These pages are the canonical, versioned replacement for the old GitHub wiki.

• Configuration
• FAQ
• Publish Flow

README Copy Section

Lepton is a lean code snippet manager powered by GitHub Gist. Check out the latest release.

Features Copy Chapter

• Unlimited public/secret snippets
• Unlimited tags
• Language groups
• Markdown/JupyterNotebook
• GitHub Enterprise
• GitHub token
• Immersive mode
• Customizable
• Built-in themes
• macOS/Win/Linux
• Dashboard
• Search snippets
• Proxy
• Free

Shortcuts Copy Chapter

See the Search FAQ for searchable fields and content-search behavior.

Customization Copy Chapter

Lepton's can be customized by <home_dir>/.leptonrc! You can find its exact path in the About page by Command/Ctrl + ,. Create the file if it does not exist.

• Theme (light, dark, one-dark, atom-one-dark, github-light, github-dark, catppuccin-latte, catppuccin-mocha, solarized-light, solarized-dark, dracula, material-theme, or ayu)
• Snippet
• Editor
• Logger
• Proxy
• Shortcuts
• Zoom
• Enterprise
• Notifications
• Interface language (i18n.locale: en, es, fr, ja, ko, tr, zh-Hans, or zh-Hant)

Check out the configuration docs to explore different customization options.
Missing a locale? See How do I add a new interface locale?

Tech Stack Copy Chapter

1. Framework: Electron
2. Bundler: Webpack, Babel, electron-builder
3. Language: ES6, Sass/SCSS
4. UI/state: React 19, Redux, React Redux, Redux Thunk
5. Editor/rendering: CodeMirror, Highlight.js, Markdown/Jupyter rendering
6. Tests/lint: Vitest, Electron smoke tests, ESLint

Now you can learn about Lepton project's code structure in DeepWiki!

Installation Copy Chapter

• macOS/Windows/Linux: Download the released packages
• macOS: Install via Homebrew

brew install --cask lepton

• Linux: Install via Snap Store

snap install lepton

Support Copy Chapter

Lepton is a free and open source project. We do not accept project donations, but if you would like to support the maintainer, you can buy me a coffee.

We also recommend donating to Wikimedia Foundation, which helps sustain free knowledge through Wikipedia and its sister projects.

Development Copy Chapter

Runtime requirements Copy Section

Lepton's current development toolchain is known to work with Node.js 24 LTS and
npm 11.x. This is the host runtime used to install dependencies and run the
webpack build; the bundled Electron app runtime is managed by the Electron
version in package.json.

Recommended:

• Node.js 24.18.0
• npm 11.16.x

If you use nvm, the repository includes an .nvmrc:

$ nvm install
$ nvm use

Apple Silicon development should use the native arm64 Node.js runtime.

Install dependencies Copy Section

$ git clone https://github.com/hackjutsu/Lepton.git
$ cd Lepton
$ npm ci

# inspect stale dependencies
$ npm run check-outdated

Client ID/Secret Copy Section

Register your application, and put your client id and client secret in ./configs/account.js.

module.exports = {
  client_id: <your_client_id>,
  client_secret: <your_client_secret>
}

configs/account.js is intentionally ignored by Git. If it is missing, the app
falls back to configs/accountDummy.js, which is useful for rendering tests but
will not support real GitHub login. Release builds create configs/account.js
from GitHub Actions secrets before packaging.

Run Copy Section

$ npm run build && npm start

For iterative renderer work, run webpack in watch mode in one terminal and
restart Electron from another terminal when needed:

$ npm run webpack-watch
$ npm start

Build Copy Section

# Development bundle
$ npm run build

# Production bundle
$ npm run webpack-prod

Automated Validation Copy Section

Use these commands before opening a pull request:

# Lint application source
$ npm run lint

# Normal local check: Vitest unit tests plus webpack development build
$ npm test

# Unit tests only
$ npm run test:unit

# Unit tests in watch mode
$ npm run test:unit:watch

The project also has Electron smoke checks. These are useful for Electron,
React, layout, preload, or packaging changes, and are run by CI.

# Launches Electron with isolated config/user-data and verifies login plus
# fixture-backed authenticated renderer surfaces
$ npm run test:smoke

# Builds an unpacked app and verifies the packaged app can render the login UI.
# This is primarily for macOS CI or release verification.
$ npm run test:packaged-smoke

Renderer smoke fixtures are opt-in through the smoke runner and use deterministic
mock state to check initial rendering. Fixture names include active, edit,
new, about, dashboard, search, delete, raw, pinned-tags, and
immersive.

# Launch one fixture directly when debugging the automated smoke check
$ npm run build
$ LEPTON_RENDER_FIXTURE=active npm start

Fixtures verify that important React surfaces mount without renderer warnings,
errors, failed loads, or crashes. They do not verify GitHub OAuth, snippet CRUD,
sync behavior, real API responses, OS shortcut delivery, or full interaction
flows.

GitHub Actions currently runs:

• lint-test-build: lint, unit tests, and webpack build verification
• electron-smoke: Electron renderer smoke test
• packaged-smoke: packaged app smoke test
• release: tag-driven cross-platform packaging and publishing

The smoke jobs are currently configured as non-blocking CI checks while the
cross-platform Electron validation continues to mature.

Manual Verification Copy Section

For UI or Electron changes, also launch the app locally:

$ npm run build && npm start

Confirm the login page visibly renders. After login, manually verify the
surfaces affected by your change, such as new snippet, edit snippet,
settings/about, dashboard, search, sync, and GitHub Gist backend interactions.
Manual verification is still required for visual quality and real GitHub
behavior; automated smoke checks do not replace backend workflow testing.

Local Packaging Copy Chapter

Build an unpacked app for the current platform.

$ npm run pack

Build apps for macOS.

$ npm run dist -- -m

Build apps for Windows.

$ npm run dist -- -w

Build apps for Linux.

Need a running Docker daemon to build a snap package.

$ npm run dist -- -l

Build apps for macOS, Windows and Linux.

$ npm run dist -- -wml

Build apps for the current OS with the current arch.

$ npm run dist

FAQ Copy Chapter

--> Wiki FAQ

Contributors Copy Chapter

License Copy Chapter

MIT © hackjutsu