Skip to content

chore: add table of contents to README #112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
eclectic-coding merged 4 commits into from
Jun 7, 2026
Merged

chore: add table of contents to README #112

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c39b949
chore: add table of contents to README
eclectic-coding Jun 7, 2026
55fbbe8
chore: add back-to-top links at the bottom of each README section
eclectic-coding Jun 7, 2026
a9f2671
chore: add CHANGELOG entry for README navigation improvements
eclectic-coding Jun 7, 2026
0e4afae
docs: add dedicated i18n section to README
eclectic-coding Jun 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Locale switcher — a `<select>` dropdown in the header lets users switch languages at runtime; locale is stored in the session and applied via `I18n.with_locale`; automatically hidden when only one locale is configured
- `config.available_locales` — controls which locales appear in the switcher (default: `[:en, :es]`)

### Changed

- README — added a table of contents, back-to-top navigation links to each major section, and a dedicated i18n section documenting locale switching, `config.available_locales`, and how to add a custom locale

## [1.5.0] - 2026-05-29

### Changed
Expand Down
95 changes: 94 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,39 @@

A production-ready operations dashboard for the full Rails Solid Stack. Mount one engine to get deep visibility into **Solid Queue** (job browser, failed job retry, queue controls, recurring tasks, performance stats), **Solid Cache** (entry browser, size distribution, write timeline), and **Solid Cable** (channel browser, message list, purge controls) — with dark mode, i18n locale switching, CSV export, alert webhooks, and a JSON metrics endpoint, all with no asset pipeline dependency.

## Table of Contents

- [Installation](#installation)
- [Screenshots](#screenshots)
- [Metrics endpoint](#metrics-endpoint)
- [General configuration](#general-configuration)
- [Authentication](#authentication)
- [Linking to the dashboard](#linking-to-the-dashboard)
- [i18n](#i18n)
- [Adding a custom locale](#adding-a-custom-locale)
- [Security](#security)
- [Authentication](#authentication-1)
- [Sensitive cache values](#sensitive-cache-values)
- [CSRF protection](#csrf-protection)
- [Rate limiting and network exposure](#rate-limiting-and-network-exposure)
- [Solid Queue](#solid-queue)
- [Features](#features)
- [Configuration](#configuration)
- [Job Filtering](#job-filtering)
- [Solid Cache](#solid-cache)
- [Features](#features-1)
- [Solid Cable](#solid-cable)
- [Features](#features-2)
- [Requirements](#requirements)
- [Versioning](#versioning)
- [Public API](#public-api)
- [Not part of the public API](#not-part-of-the-public-api)
- [Deprecation policy](#deprecation-policy)
- [Contributing](#contributing)
- [License](#license)

---

## Installation

Add the gem to your application's `Gemfile`:
Expand All @@ -30,12 +63,16 @@ rails generate solid_stack_web:install

This creates `config/initializers/solid_stack_web.rb` with every configuration option commented inline, and injects `mount SolidStackWeb::Engine, at: "/solid_stack"` into `config/routes.rb`. The dashboard will then be available at `/solid_stack` (or whatever path you choose).

[↑ Back to top](#table-of-contents)

---

## Screenshots

![SolidStackWeb dashboard](docs/screenshots/demo.gif)

[↑ Back to top](#table-of-contents)

---

## Metrics endpoint
Expand Down Expand Up @@ -64,6 +101,8 @@ This creates `config/initializers/solid_stack_web.rb` with every configuration o

`slow_jobs` is only present when `slow_job_threshold` is configured. The endpoint is protected by the same authentication as the rest of the dashboard.

[↑ Back to top](#table-of-contents)

---

## General configuration
Expand Down Expand Up @@ -99,6 +138,40 @@ The `authenticate` block is evaluated in the context of each request's controlle
link_to "Queue Dashboard", SolidStackWeb.mount_path
```

[↑ Back to top](#table-of-contents)

---

## i18n

All dashboard UI strings — page titles, table headers, button labels, empty states, flash messages, and sparkline tooltips — are backed by locale YAML files. The engine ships with **English (`en`)** and **Spanish (`es`)** built in.

A language selector appears in the dashboard header and lets users switch locales at runtime. The selected locale is stored in the session and applied via `I18n.with_locale`, so it persists across requests without touching the host application's locale. The `?locale=` query param takes precedence over the session value, making it easy to deep-link to a specific language.

The switcher is automatically hidden when `config.available_locales` contains only one entry.

```ruby
SolidStackWeb.configure do |config|
# Locales shown in the language switcher (default: [:en, :es]).
# Set to [:en] to hide the switcher entirely.
config.available_locales = [:en, :es]
end
```

### Adding a custom locale

1. Create a locale file in your host application under `config/locales/`, e.g. `config/locales/solid_stack_web.fr.yml`.
2. Nest all keys under `fr > solid_stack_web:` — use `config/locales/en.yml` in the gem as a reference for the full key list.
3. Add the locale symbol to `config.available_locales`:

```ruby
config.available_locales = [:en, :es, :fr]
```

Rails will pick up the file automatically via its standard `config.i18n.load_path`; no additional configuration is needed.

[↑ Back to top](#table-of-contents)

---

## Security
Expand Down Expand Up @@ -137,6 +210,8 @@ The dashboard is designed to be mounted behind your application's existing authe
- Restricting access by IP at the reverse-proxy level
- Applying [Rack::Attack](https://github.com/rack/rack-attack) rules to the mount path

[↑ Back to top](#table-of-contents)

---

## Solid Queue
Expand Down Expand Up @@ -215,6 +290,8 @@ The jobs list supports four independent filters, all driven by query params:

Filters are preserved when switching between status tabs (Ready / Scheduled / Running / Blocked) and when discarding a job. They can be combined freely.

[↑ Back to top](#table-of-contents)

---

## Solid Cache
Expand All @@ -231,6 +308,8 @@ Filters are preserved when switching between status tabs (Ready / Scheduled / Ru
- **Delete entry** — per-row delete button or detail-page button removes a single cache entry
- **Flush All** — header button deletes every cache entry with a confirmation prompt

[↑ Back to top](#table-of-contents)

---

## Solid Cable
Expand All @@ -243,6 +322,8 @@ Filters are preserved when switching between status tabs (Ready / Scheduled / Ru
- **Per-channel message list** — `GET /cable/channels/:channel_hash` shows a paginated, reverse-chronological list of that channel's `SolidCable::Message` records; each row shows the message ID, a truncated payload preview (120 chars) with the full payload on hover, and a relative sent time with the exact timestamp on hover; supports `?q=` filtering by payload substring; **Purge Channel** button deletes all messages for the channel
- **Message purge** — "Purge Old" form on the channel browser deletes all messages older than 1, 7, or 30 days; confirmation prompt before any destructive action

[↑ Back to top](#table-of-contents)

---

## Requirements
Expand All @@ -255,6 +336,10 @@ Filters are preserved when switching between status tabs (Ready / Scheduled / Ru
- [turbo-rails](https://github.com/hotwired/turbo-rails) >= 2.0
- [importmap-rails](https://github.com/rails/importmap-rails) >= 1.2

[↑ Back to top](#table-of-contents)

---

## Versioning

SolidStackWeb follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
Expand Down Expand Up @@ -283,6 +368,8 @@ The following are internal and may change in any release without notice:

When a public API item is renamed or removed, the old interface is deprecated in a **minor** release — it continues to work but issues an `ActiveSupport::Deprecation` warning pointing to the replacement. The old interface is removed in the next **major** release. The [UPGRADING.md](UPGRADING.md) file documents every breaking change and the migration steps.

[↑ Back to top](#table-of-contents)

---

## Contributing
Expand All @@ -294,6 +381,12 @@ When a public API item is renamed or removed, the old interface is deprecated in

Bug reports and feature requests are welcome on [GitHub Issues](https://github.com/eclectic-coding/solid_stack_web/issues).

[↑ Back to top](#table-of-contents)

---

## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

[↑ Back to top](#table-of-contents)