From 7d4e5d17fced55045138708af352c20f3ff68c93 Mon Sep 17 00:00:00 2001 From: Matthew Kilgore Date: Tue, 18 Jun 2024 12:38:33 -0400 Subject: [PATCH] chore: docs updates for landing page --- docs/.vitepress/config.mts | 8 ++++++ docs/docs/index.md | 56 -------------------------------------- docs/import-csv.md | 21 +++++++------- docs/index.md | 44 +++++++++++++++++++++++++----- docs/tips-tricks.md | 18 ++++++------ 5 files changed, 66 insertions(+), 81 deletions(-) delete mode 100644 docs/docs/index.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index ab6d8246..aca216fe 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -4,8 +4,16 @@ import { defineConfig } from 'vitepress' export default defineConfig({ title: "HomeBox", description: "A simple home inventory management software", + lastUpdated: true, themeConfig: { logo: '/lilbox.svg', + + search: { + provider: 'local' + }, + editLink: { + pattern: 'https://github.com/sysadminsmedia/homebox/edit/main/docs/:path' + }, // https://vitepress.dev/reference/default-theme-config nav: [ { text: 'Home', link: '/' }, diff --git a/docs/docs/index.md b/docs/docs/index.md deleted file mode 100644 index 2772c8ad..00000000 --- a/docs/docs/index.md +++ /dev/null @@ -1,56 +0,0 @@ -

-
- -
- Homebox -
-

-

- Docs - | - Demo - | - Discord -

- - - -Homebox is the inventory and organization system built for the Home User! With a focus on simplicity and ease of use, Homebox is the perfect solution for your home inventory, organization, and management needs. While developing this project, I've tried to keep the following principles in mind: - -- _Simple_ - Homebox is designed to be simple and easy to use. No complicated setup or configuration required. Use either a single docker container, or deploy yourself by compiling the binary for your platform of choice. -- _Blazingly Fast_ - Homebox is written in Go, which makes it extremely fast and requires minimal resources to deploy. In general idle memory usage is less than 50MB for the whole container. -- _Portable_ - Homebox is designed to be portable and run on anywhere. We use SQLite and an embedded Web UI to make it easy to deploy, use, and backup. - -## Project Status - -Homebox is currently in early active development and is currently in **beta** stage. This means that the project may still be unstable and clunky. Overall, we are striving to not introduce any breaking changes and have checks in place to ensure migrations and upgrades are smooth. However, we do not guarantee that there will be no breaking changes. We will try to keep the documentation up to date as we make changes. - -## Features - -- Create and Manage _Items_ by providing a name and a description - That's it! Homebox requires only a few details to be provided to create an item, after that you can specify as much detail as you want, or hide away some of the things you won't ever need. -- Optional Details for Items include - - Warranty Information - - Sold To Information - - Purchased From Information - - Item Identifications (Serial, Model, etc) - - Categorized Attachments (Images, Manuals, General) - - Arbitrary/Custom Fields -- CSV Import/Export for quickly creating and managing items -- Custom Reporting - - Bill of Materials Export - - QR Code Label Generator -- Organize _Items_ by creating _Labels_ and _Locations_ and assigning them to items. -- Multi-Tenant Support - All users are placed in a group and can only see items in their group. Invite family members to your group, or share an instance among friends! - - -## Why Not Use Something Else? - -There are a lot of great inventory management systems out there, but none of them _really_ fit my needs as a home user. Snipe-IT is a fantastic product that has so many robust features and management options which makes it easy to become overwhelmed and confused. I wanted something that was simple and easy to use that didn't require a lot of cognitive overhead to manage. I primarily built this to organize my IOT devices and save my warranty and documentation information in a central, searchable location. - -### Spreadsheet - -That's a fair point. If your needs can be fulfilled by a Spreadsheet, I'd suggest using that instead. I've found spreadsheets get pretty unwieldy when you have a lot of data, and it's hard to keep track of what's where. I also wanted to be able to search and filter my data in a more robust way than a spreadsheet can provide. I also wanted to leave the door open for more advanced features in the future like maintenance logs, moving label generators, and more. - -### Snipe-It? - -Snipe-It is the gold standard for IT management. If your use-case is to manage consumables and IT physical infrastructure, I highly suggest you look at Snipe-It over Homebox, it's just more purpose built for that use case. Homebox is, in contrast, purpose built for the home user, which means that we try to focus on keeping things simple and easy to use. Lowering the friction for creating items and managing them is a key goal of Homebox which means you lose out on some of the more advanced features. In most cases, this is a good trade-off. \ No newline at end of file diff --git a/docs/import-csv.md b/docs/import-csv.md index 6ed4f4b5..03fe2852 100644 --- a/docs/import-csv.md +++ b/docs/import-csv.md @@ -11,8 +11,9 @@ Using the CSV import is the recommended way for adding items to the database. It - CSV Exports do not support nested path exports (e.g. `Home / Office / Desk`) and will only export the Items direct parent, (though imports _do_ support nested paths) - Cannot specify item-to-item relationships (e.g. `Item A` is a child of `Item B`) -!!! tip "File Formats" - The CSV import supports both CSV and TSV files. The only difference is the delimiter used. CSV files use a comma `,` as the delimiter and TSV files use a tab `\t` as the delimiter. The file extension does not matter. +::: tip "File Formats" +The CSV import supports both CSV and TSV files. The only difference is the delimiter used. CSV files use a comma `,` as the delimiter and TSV files use a tab `\t` as the delimiter. The file extension does not matter. +::: ## CSV Reference @@ -24,20 +25,20 @@ Below are the supported columns. They are case-sensitive, can be in any ordered : Import Refs are unique strings that can be used to deduplicate imports. Before an item is imported, we check the database for a matching ref. If the ref exists, we skip the creation of that item. - * String Type - * Max 100 Characters + * String Type + * Max 100 Characters - Import Refs are used to de-duplicate imports. It is HIGHLY recommended that you use them to manage your items if you intend to manage your inventory via CSV import/export. If you do not use import refs, you will end up with duplicate items in your database on subsequent imports. + Import Refs are used to de-duplicate imports. It is HIGHLY recommended that you use them to manage your items if you intend to manage your inventory via CSV import/export. If you do not use import refs, you will end up with duplicate items in your database on subsequent imports. - !!! tip - - Specifying import refs also allows you to update existing items via the CSV import. If you specify an import ref that already exists in the database, we will update the existing item instead of creating a new one. +::: tip +Specifying import refs also allows you to update existing items via the CSV import. If you specify an import ref that already exists in the database, we will update the existing item instead of creating a new one. +::: `HB.location` : This is the location of the item that will be created. These are de-duplicated and won't create another instance when reused. - * Supports Path Separators for nested locations (e.g. `Home / Office / Desk`) + * Supports Path Separators for nested locations (e.g. `Home / Office / Desk`) `HB.labels` @@ -47,7 +48,7 @@ Below are the supported columns. They are case-sensitive, can be in any ordered : This is a special column that allows you to add custom fields to the item. The column name must start with `HB.field.` followed by the name of the field. The value of the column will be the value of the field. - - If the cell value is empty, it will be ignored. + - If the cell value is empty, it will be ignored. ### Standard Columns diff --git a/docs/index.md b/docs/index.md index c5724c37..2105fe9b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,7 +5,9 @@ layout: home hero: name: "HomeBox" text: "A simple home inventory management software" - tagline: My great project tagline + image: + src: /lilbox.svg + alt: HomeBox logo actions: - theme: brand text: Quick Start @@ -15,11 +17,39 @@ hero: link: /tips-tricks features: - - title: Feature A - details: Lorem ipsum dolor sit amet, consectetur adipiscing elit - - title: Feature B - details: Lorem ipsum dolor sit amet, consectetur adipiscing elit - - title: Feature C - details: Lorem ipsum dolor sit amet, consectetur adipiscing elit + - title: Add/Update/Delete Items + details: You can add, update and delete your own items in inventory simply + - title: Optional details + details: Optional extra details like warranty information, and item identifications + - title: CSV Import/Export + details: Import a CSV file to quickly get started with existing information, or export to save information + - title: Custom Report + details: Export bill of mertials, or generate QR codes for items + - title: Custom labeling and locations + details: Use custom labels and locations to organize items + - title: Multi-Tenant Support + details: All users are in a group, and can only see what's in the group. Invite family memebers or share an instance with friends. --- +Homebox is the inventory and organization system built for the Home User! With a focus on simplicity and ease of use, Homebox is the perfect solution for your home inventory, organization, and management needs. While developing this project, I've tried to keep the following principles in mind: + +- _Simple_ - Homebox is designed to be simple and easy to use. No complicated setup or configuration required. Use either a single docker container, or deploy yourself by compiling the binary for your platform of choice. +- _Blazingly Fast_ - Homebox is written in Go, which makes it extremely fast and requires minimal resources to deploy. In general idle memory usage is less than 50MB for the whole container. +- _Portable_ - Homebox is designed to be portable and run on anywhere. We use SQLite and an embedded Web UI to make it easy to deploy, use, and backup. + +## Project Status + +Homebox is currently in early active development and is currently in **beta** stage. This means that the project may still be unstable and clunky. Overall, we are striving to not introduce any breaking changes and have checks in place to ensure migrations and upgrades are smooth. However, we do not guarantee that there will be no breaking changes. We will try to keep the documentation up to date as we make changes. + + +## Why Not Use Something Else? + +There are a lot of great inventory management systems out there, but none of them _really_ fit my needs as a home user. Snipe-IT is a fantastic product that has so many robust features and management options which makes it easy to become overwhelmed and confused. I wanted something that was simple and easy to use that didn't require a lot of cognitive overhead to manage. I primarily built this to organize my IOT devices and save my warranty and documentation information in a central, searchable location. + +### Spreadsheet + +That's a fair point. If your needs can be fulfilled by a Spreadsheet, I'd suggest using that instead. I've found spreadsheets get pretty unwieldy when you have a lot of data, and it's hard to keep track of what's where. I also wanted to be able to search and filter my data in a more robust way than a spreadsheet can provide. I also wanted to leave the door open for more advanced features in the future like maintenance logs, moving label generators, and more. + +### Snipe-It? + +Snipe-It is the gold standard for IT management. If your use-case is to manage consumables and IT physical infrastructure, I highly suggest you look at Snipe-It over Homebox, it's just more purpose built for that use case. Homebox is, in contrast, purpose built for the home user, which means that we try to focus on keeping things simple and easy to use. Lowering the friction for creating items and managing them is a key goal of Homebox which means you lose out on some of the more advanced features. In most cases, this is a good trade-off. \ No newline at end of file diff --git a/docs/tips-tricks.md b/docs/tips-tricks.md index f0002038..00163d49 100644 --- a/docs/tips-tricks.md +++ b/docs/tips-tricks.md @@ -11,8 +11,9 @@ Custom fields are a great way to add any extra information to your item. The fol Custom fields are appended to the main details section of your item. -!!! tip - Homebox Custom Fields also have special support for URLs. Provide a URL (`https://google.com`) and it will be automatically converted to a clickable link in the UI. Optionally, you can also use Markdown syntax to add a custom text to the button. `[Google](https://google.com)` +::: tip +Homebox Custom Fields also have special support for URLs. Provide a URL (`https://google.com`) and it will be automatically converted to a clickable link in the UI. Optionally, you can also use Markdown syntax to add a custom text to the button. `[Google](https://google.com)` +::: ## Managing Asset IDs @@ -30,18 +31,19 @@ This is the default behavior likely to experience the most consistency. Whenever In some cases, you may want to skip some items such as consumables, or items that are loosely tracked. In this case, we recommend that you leave auto-incrementing IDs enabled _however_ when you create a new item that you want to skip, you can go to that item and reset the ID to 0. This will remove it from the auto-incrementing sequence, and the next item will receive the next available ID. -!!! tip - If you're migrating from an older version, there is an action on the user's profile page to assign IDs to all items. This will assign the next available ID to all items in order of their creation. You should __only do this once__ during the migration process. You should be especially cautious with this if you're using the reset feature described in [option number 2](#2-auto-incrementing-ids-with-reset) +::: tip +If you're migrating from an older version, there is an action on the user's profile page to assign IDs to all items. This will assign the next available ID to all items in order of their creation. You should __only do this once__ during the migration process. You should be especially cautious with this if you're using the reset feature described in [option number 2](#2-auto-incrementing-ids-with-reset) +::: ## QR Codes -:octicons-tag-24: 0.7.0 +:label: 0.7.0 Homebox has a built-in QR code generator that can be used to generate QR codes for your items. This is useful for tracking items with a mobile device. You can generate a QR code for any item by clicking the QR code icon in the top right of the item details page. The same can be done for the Labels and Locations page. Currently, support is limited to generating one-off QR Codes. However, the API endpoint is available for generating QR codes on the fly for any item (or any other data) if you provide a valid API key in the query parameters. An example url would look like `/api/v1/qrcode?data=https://homebox.fly.dev/item/{uuid}`. Currently, the easiest way to get an API token is to use one from an existing URL of the QR Code in the API key, but this will be improved in the future. -:octicons-tag-24: v0.8.0 +:label: v0.8.0 In version 0.8.0 We've added a custom label generation. On the tools page, there is now a link to the label-generator page where you can generate labels based on Asset ID for your inventory. These are still in early development, so please provide feedback. There's also more information on the implementation on the label generator page. @@ -49,7 +51,7 @@ In version 0.8.0 We've added a custom label generation. On the tools page, there ## Scheduled Maintenance Notifications -:octicons-tag-24: v0.9.0 +:label: v0.9.0 Homebox uses [shoutrrr](https://containrrr.dev/shoutrrr/0.7/) to send notifications. This allows you to send notifications to a variety of services. On your profile page, you can add notification URLs to your profile which will be used to send notifications when a maintenance event is scheduled. @@ -60,7 +62,7 @@ As of `v0.9.0` we have limited support for complex scheduling of maintenance eve ## Custom Currencies -:octicons-tag-24: v0.11.0 +:label: v0.11.0 Homebox allows you to add additional currencies to your instance by specify a JSON file containing the currencies you want to add.