feat: prepare for initial release

Signed-off-by: Lukas Frey <[email protected]>

README.md

@@ -1,14 +1,18 @@
 ![filament-knowledge-base Banner](docs/images/banner.jpg)
 
 
-# A filament plugin that adds a knowledge base and help to your filament panel(s).
+# A filament plugin that adds a knowledge base and documentation to your filament panel(s).
 
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/guava/filament-knowledge-base.svg?style=flat-square)](https://packagist.org/packages/guava/filament-knowledge-base)
 [![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/guava/filament-knowledge-base/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/guava/filament-knowledge-base/actions?query=workflow%3Arun-tests+branch%3Amain)
 [![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/guava/filament-knowledge-base/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/guava/filament-knowledge-base/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
 [![Total Downloads](https://img.shields.io/packagist/dt/guava/filament-knowledge-base.svg?style=flat-square)](https://packagist.org/packages/guava/filament-knowledge-base)
 
-This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
+Did your filament panel ever get complex real quick? Ever needed to a place to document all your features in one place?
+
+Filament Knowledge Base is here for exactly this reason!
+
+Using our Knowledge Base package, you can write markdown documentation files to document every feature of your package and give your users a comprehensive knowledge base tailored for your product. Right inside Filament!
 
 ## Showcase
 
@@ -28,13 +32,6 @@ You can install the package via composer:
 composer require guava/filament-knowledge-base
 ```
 
-You can publish and run the migrations with:
-
-```bash
-php artisan vendor:publish --tag="filament-knowledge-base-migrations"
-php artisan migrate
-```
-
 You can publish the config file with:
 
 ```bash
@@ -48,19 +45,129 @@ return [
 ];
 ```
 
-Optionally, you can publish the views using
+## Introduction
+### Knowledge Base Panel
+We register a separate panel for your entire Knowledge Base. This way you have a single place where you can in detail document your functionalities.
+
+### Modal Previews
+
+## Storage
+We currently support flat file (stored inside the source project) storage out of the box.
+
+You can choose to store your documentation in:
+ - Markdown files (Preferred method)
+ - PHP classes (for complex cases)
+
+In the future, we plan to also ship a Database Driver so you can store your documentation in the database.
 
+## Usage
+
+### Register plugin
+To begin, register the `KnowledgeBasePlugin` in all your Filament Panels from which you want to access your Knowledge Base / Documentation.
+
+```php
+use Filament\Panel;
+use Guava\FilamentKnowledgeBase\KnowledgeBasePlugin;
+
+public function panel(Panel $panel): Panel
+{
+    return $panel
+        ->plugins([
+            // ...
+            KnowledgeBasePlugin::make(),
+        ])
+}
+```
+
+### Create documentation
+To create your first documentation, simply run the `docs:make`, such as:
 ```bash
-php artisan vendor:publish --tag="filament-knowledge-base-views"
+php artisan docs:make prologue.getting-started
 ```
+This will create a file in `/docs/en/prologue/getting-started.md`.
 
-## Usage
+If you want to create the file for a specific locale, you can do so using the `--locale` option (can be repeated for multiple locales):
+```bash
+php artisan docs:make prologue.getting-started --locale=de --locale=en
+```
+This would create the file for both the `de` and `en` locale.
 
+If you **don't** pass any locale, it will automatically create the documentation file for every locale in `/docs/{locale}`.
+
+### Markdown
+After you generated your documentation file, it's time to edit it.
+
+A markdown file consists of two sections, the `Front Matter` and `Content`.
+
+#### Front Matter
+In the front matter, you can customize the documentation page, such as the title, the icon and so on:
+```md
+---
+// Anything between these dashes is the front matter
+title: My example documentation
+icon: heroicon-o-book-open
+---
+```
+
+#### Content
+Anything after the front matter is your content, written in markdown:
+```md
+---
+// Front matter ... 
+---
+# Introduction
+Lorem ipsum dolor ....
+```
+And that's it! You've created a simple knowledge base inside Filament.
+
+### Accessing the knowledge base
+In every panel you registered the Knowlege Base plugin, we automatically inject a documentation button at the very bottom of the sidebar.
+
+[SCREENSHOT HERE]
+
+But we offer a deeper integration to your panels.
+
+#### Integrating into resources
+You will most likely have a section in your knowledge base dedicated to each of your resource (at least to the more complex ones).
+
+To integrate your resource with the documentation, all you need to do is implement the `HasKnowledgeBase` contract in your resource.
+
+This will require you to implement the `getDocumentation` method, where you simply return the documentation pages you want to integrate. You can either return the `IDs` as strings (dot-separated path inside `/docs/{locale}/`) or use the helper to retrieve the model:
 ```php
-$filamentKnowledgeBase = new Guava\FilamentKnowledgeBase();
-echo $filamentKnowledgeBase->echoPhrase('Hello, Guava!');
+use use Guava\FilamentKnowledgeBase\Contracts\HasKnowledgeBase;
+
+class UserResource extends Resource implements HasKnowledgeBase
+{
+    // ...
+
+    // 
+    public static function getDocumentation(): array
+    {
+        return [
+            'users.introduction',
+            'users.authentication',
+            FilamentKnowledgeBase::model()::find('users.permissions'),
+        ];
+    }
+}
 ```
 
+### Accessing the documentation models
+We use the `sushi` package in the background to store the documentations. This way, they behave almost like regular `Eloquent models`.
+
+#### Get model using our helper
+To get the model, simply use our helper `FilamentKnowledgeBase::model()`:
+```php
+use \Guava\FilamentKnowledgeBase\FilamentKnowledgeBase;
+
+// find specific model
+FilamentKnowledgeBase::model()::find('<id>');
+// query models
+FilamentKnowledgeBase::model()::query()->where('title', 'Some title');
+// etc.
+```
+
+
 ## Testing
 
 ```bash
@@ -83,7 +190,8 @@ Please review [our security policy](../../security/policy) on how to report secu
 
 - [Lukas Frey](https://github.com/GuavaCZ)
 - [All Contributors](../../contributors)
-- Spatie - Our package filament-knowledge-base is a modified version of [Spatie's Package FilamentKnowledgeBase](https://github.com/spatie/package-filament-knowledge-base-laravel)
+- Spatie - Our package skeleton is a modified version of [Spatie's Package Tools](https://github.com/spatie/laravel-package-tools)
+- Spatie shiki and markdown packages
 
 ## License
 

bin/grammars.js

@@ -0,0 +1,14 @@
+const args = process.argv.slice(2);
+
+async function main(args) {
+    const {grammars} = await import('tm-grammars');
+    const language = args[0];
+    const meta = grammars
+        .find(obj => obj.name === language ||
+            (obj.hasOwnProperty('aliases') && obj.aliases.includes(language))
+        );
+    process.stdout.write(meta ? meta.displayName : 'Text');
+}
+
+
+main(args)

composer.json

@@ -17,12 +17,13 @@
     ],
     "require": {
         "php": "^8.1",
+        "calebporzio/sushi": "^2.5",
         "filament/filament": "^3.2",
         "illuminate/contracts": "^10.0|^11.0",
         "league/commonmark": "^2.4",
-        "spatie/laravel-markdown": "^2.5",
         "spatie/laravel-package-tools": "^1.14.0",
         "spatie/php-structure-discoverer": "^2.1",
+        "spatie/shiki-php": "^2.0",
         "symfony/yaml": "^6.4"
     },
     "require-dev": {

config/filament-knowledge-base.php

@@ -2,8 +2,16 @@
 
 // config for Guava/FilamentKnowledgeBase
 return [
-    'id' => env('FILAMENT_KB_ID', 'knowledge-base'),
-    'path' => env('FILAMENT_KB_PATH', 'kb'),
-    'guest-access' => env('FILAMENT_KB_GUEST_ACCESS', true),
-    'theme-path' => 'resources/css/filament/admin/theme.css',
+    'panel' => [
+        'id' => env('FILAMENT_KB_ID', 'knowledge-base'),
+        'path' => env('FILAMENT_KB_PATH', 'kb'),
+        'guest-access' => env('FILAMENT_KB_GUEST_ACCESS', true),
+        'theme-path' => 'resources/css/filament/admin/theme.css',
+    ],
+
+    'docs-path' => env('FILAMENT_KB_DOCS_PATH', 'docs'),
+
+    'model' => \Guava\FilamentKnowledgeBase\Models\FlatfileDocumentation::class,
+
+    'file-name' => '\d+-(.*)(?=\.)',
 ];

package.json

@@ -1,9 +1,10 @@
 {
-  "devDependencies": {
+    "devDependencies": {
     "conventional-changelog-conventionalcommits": "^7.0.2",
     "semantic-release": "^22.0.5"
   },
   "dependencies": {
-    "shiki": "^1.2.3"
+    "shiki": "^1.2.3",
+    "tm-grammars": "^1.7.2"
   }
 }

resources/lang/cs/translations.php

@@ -0,0 +1,8 @@
+<?php
+
+return [
+    'knowledge-base' => 'Dokumentace',
+    'help' => 'Nápověda',
+    'open-documentation' => 'Otevřít dokumentaci',
+    'close' => 'Zavřít',
+];

resources/lang/de/translations.php

@@ -0,0 +1,8 @@
+<?php
+
+return [
+    'knowledge-base' => 'Dokumentation',
+    'help' => 'Hilfe',
+    'open-documentation' => 'Dokumentation öffnen',
+    'close' => 'Schließen',
+];

resources/lang/en/translations.php

@@ -0,0 +1,8 @@
+<?php
+
+return [
+    'knowledge-base' => 'Documentation',
+    'help' => 'Help',
+    'open-documentation' => 'Open documentation',
+    'close' => 'Close',
+];

resources/views/code-block.blade.php

@@ -0,0 +1,41 @@
+@pushonce('styles')
+    <style>
+        @import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono&display=swap');
+
+        .shiki * {
+            font-family: "JetBrains Mono", monospace;
+            font-optical-sizing: auto;
+            font-weight: 400;
+            font-style: normal;
+        }
+    </style>
+@endpushonce
+
+<div @class([
+    "bg-gray-900 text-gray-200 dark:bg-gray-800/80 rounded-lg p-2 pt-0 mb-4",
+])
+     x-data
+>
+    <div class="text-xs text-white/50 py-2 px-1 flex flex-row items-center justify-between">
+        <span>{{$language}}</span>
+        <span
+            class="hover:cursor-pointer hover:text-white/70 flex items-center justify-center gap-1 text-xs"
+            x-on:click.prevent="
+        if (navigator.clipboard) {
+        navigator.clipboard.writeText($root.querySelector('.shiki').textContent);
+        new FilamentNotification().title('Code copied to your clipboard.').success().send();
+        }
+        const range = document.createRange();
+        range.selectNodeContents($root.querySelector('.shiki'));
+        window.getSelection().removeAllRanges();
+        window.getSelection().addRange(range);
+        ">
+            <x-icon name='heroicon-o-clipboard' class='w-4 h-4'/>
+            <span x-show="navigator.clipboard">Copy</span>
+            <span x-show="! navigator.clipboard">Select</span>
+        </span>
+    </div>
+    <div class="rounded-lg p-4 leading-relaxed bg-gray-700/80 [&_.shiki]:!bg-transparent">
+        {!! $code !!}
+    </div>
+</div>