Skip to content

Improve docs site #285

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
danvergara merged 2 commits into from
Oct 21, 2025
Merged

Improve docs site #285

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c55a7b3
docs(mkdocs): add a logo to the docs site
danvergara Oct 21, 2025
6763a6e
docs(mkdocs): update docs to catch up with the latest changes
danvergara Oct 21, 2025
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
Binary file added docs/assets/images/dblab-logo.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
31 changes: 29 additions & 2 deletions docs/tutorials/navigation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ One of the main features of dblab is to be a simple but very useful UI to intera
![dblab](https://raw.githubusercontent.com/danvergara/dblab/main/assets/tutorials/images/full-ui.png){ width="700" : .center }

- <kbd>Ctrl+I</kbd> to move from Rows to Indexes and backwards.
- <kbd>Ctrl+F</kbd> to move from Rows to Constraints and backwards.
- <kbd>Ctrl+T</kbd> to move from Rows to Constraints and backwards.
- <kbd>Ctrl+S</kbd> to move from Rows to Structure and backwards.

When selected each panel will show different information in the bottom box:
Expand All @@ -27,4 +27,31 @@ To navigate there you can use:

Once you are placed above the correct name in the menu press <kbd>Enter</kbd> to select the table.
Now you can navigate to the different panels to see the information related to it.
![dblab](https://raw.githubusercontent.com/danvergara/dblab/main/assets/tutorials/images/left-menu.png){ width="400" : .center }
![dblab](https://raw.githubusercontent.com/danvergara/dblab/main/assets/tutorials/images/left-menu.png){ width="400" : .center }

### Key Bindings
Key | Description
----------------------------------------|---------------------------------------
<kbd>Ctrl+Space</kbd> | If the query panel is active, execute the query
<kbd>Ctrl+D</kbd> | Cleans the whole text from the query editor, when the editor is selected
<kbd>Enter</kbd> | If the tables panel is active, list all the rows as a result set on the rows panel and display the structure of the table on the structure panel
<kbd>Ctrl+S</kbd> | If the rows panel is active, switch to the schema panel. The opposite is true
<kbd>Ctrl+T</kbd> | If the rows panel is active, switch to the constraints view. The opposite is true
<kbd>Ctrl+I</kbd> | If the rows panel is active, switch to the indexes view. The opposite is true
<kbd>Ctrl+H</kbd> | Toggle to the panel on the left
<kbd>Ctrl+J</kbd> | Toggle to the panel below
<kbd>Ctrl+K</kbd> | Toggle to the panel above
<kbd>Ctrl+L</kbd> | Toggle to the panel on the right
<kbd>Arrow Up</kbd> | Next row of the result set on the panel. Views: rows, table, constraints, structure and indexes
<kbd>k</kbd> | Next row of the result set on the panel. Views: rows, table, constraints, structure and indexes
<kbd>Arrow Down</kbd> | Previous row of the result set on the panel. Views: rows, table, constraints, structure and indexes
<kbd>j</kbd> | Previous row of the result set on the panel. Views: rows, table, constraints, structure and indexes
<kbd>Arrow Right</kbd> | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes
<kbd>l</kbd> | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes
<kbd>Arrow Left</kbd> | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes
<kbd>h</kbd> | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes
<kbd>g</kbd> | Move cursor to the top of the panel's dataset. Views: rows, constraints, structure and indexes
<kbd>G</kbd> | Move cursor to the bottom of the panel's dataset. Views: rows, constraints, structure and indexes
<kbd>Ctrl-F</kbd> | Move down by one page. Views: rows, constraints, structure and indexes
<kbd>Ctrl-B</kbd> | Move up by one page. Views: rows, constraints, structure and indexes
<kbd>Ctrl+c</kbd> | Quit
12 changes: 7 additions & 5 deletions docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,11 @@ If you want to see the rows of a table, press <kbd>Enter</kbd>.

To see the schema of a table, locate yourself on the `rows` panel and press <kbd>Ctrl+S</kbd> to switch to the `structure` panel, then switch <kbd>Ctrl+S</kbd> to switch back.

The same can be achieved for the `constraints` view by pressing <kbd>Ctrl+F</kbd> to go back and forth between the `rows` and the `constraints` panels.
The same can be achieved for the `constraints` view by pressing <kbd>Ctrl+T</kbd> to go back and forth between the `rows` and the `constraints` panels.

The `--db` flag is now optional (except for Oracle), meaning that the user will be able to see the list of databases they have access to. The regular list of tables will be replaced with a tree structure showing a list of databases and their respective list of tables, branching off each database. Due to the nature of the vast majority of DBMSs that don't allow cross-database queries, dblab has to open an independent connection for each database. The side effect of this decision, is that the user has to press `Enter` on the specific database of interest. An indicator showing the current active database will appear at the bottom-right of the screen. To change the focus, just hit enter on another database. Once a database is selected, the usual behavior of inspecting tables remains the same.

<img src="https://raw.githubusercontent.com/danvergara/dblab/main/screenshots/tree-view.png" />

Now, there's a menu to navigate between hidden views by just clicking on the desired options:

Expand All @@ -87,8 +91,7 @@ Now, there's a menu to navigate between hidden views by just clicking on the des
![Alt Text](https://raw.githubusercontent.com/danvergara/dblab/main/screenshots/constraints-view.png){ width="700" : .center }
![Alt Text](https://raw.githubusercontent.com/danvergara/dblab/main/screenshots/indexes-view.png){ width="700" : .center }

As you may have noticed, navigation has already been added, so every time you query the content of a listed table, the result set is going to be paginated. This allows to the user dealing with large tables, optimizing resources.
Just hit the `BACK` and `NEXT` buttons to go back and forth.


### Key Bindings
Key | Description
Expand All @@ -97,7 +100,7 @@ Key | Description
<kbd>Ctrl+D</kbd> | Cleans the whole text from the query editor, when the editor is selected
<kbd>Enter</kbd> | If the tables panel is active, list all the rows as a result set on the rows panel and display the structure of the table on the structure panel
<kbd>Ctrl+S</kbd> | If the rows panel is active, switch to the schema panel. The opposite is true
<kbd>Ctrl+F</kbd> | If the rows panel is active, switch to the constraints view. The opposite is true
<kbd>Ctrl+T</kbd> | If the rows panel is active, switch to the constraints view. The opposite is true
<kbd>Ctrl+I</kbd> | If the rows panel is active, switch to the indexes view. The opposite is true
<kbd>Ctrl+H</kbd> | Toggle to the panel on the left
<kbd>Ctrl+J</kbd> | Toggle to the panel below
Expand All @@ -111,7 +114,6 @@ Key | Description
<kbd>l</kbd> | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes
<kbd>Arrow Left</kbd> | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes
<kbd>h</kbd> | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes
<kbd>h</kbd> | Horizontal scrolling on the panel. Views: rows, constraints, structure and indexes
<kbd>g</kbd> | Move cursor to the top of the panel's dataset. Views: rows, constraints, structure and indexes
<kbd>G</kbd> | Move cursor to the bottom of the panel's dataset. Views: rows, constraints, structure and indexes
<kbd>Ctrl-F</kbd> | Move down by one page. Views: rows, constraints, structure and indexes
Expand Down
24 changes: 12 additions & 12 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,18 @@ theme:
features:
- content.code.copy
favicon: assets/images/favicon.ico
logo: assets/images/dblab-logo.png
palette:
- media: '(prefers-color-scheme: light)'
scheme: default
primary: blue
primary: indigo
accent: teal
toggle:
icon: material/lightbulb
name: Switch to light mode
- media: '(prefers-color-scheme: dark)'
scheme: slate
primary: blue
primary: indigo
accent: teal
toggle:
icon: material/lightbulb-outline
Expand All @@ -29,16 +30,15 @@ plugins:
- search
- termynal
nav:
- dblab: index.md
- quickstart.md
- Tutorials:
- First steps: tutorials/index.md
- tutorials/navigation.md
- Config File: tutorials/config-file.md
- usage.md
- features.md
- release-notes.md
- contribute.md
- Home: index.md
- Quickstart: quickstart.md
- Usage: usage.md
- Tutorials:
- Getting Started: tutorials/index.md
- Navigation: tutorials/navigation.md
- Config File: tutorials/config-file.md
- Contribute: contribute.md
- Release Notes: release-notes.md

markdown_extensions:
- toc:
Expand Down