diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 0f222ecd..b389be5f 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -97,7 +97,7 @@ jobs: uses: docker/setup-buildx-action@v3 - name: Install Task uses: go-task/setup-task@v1 - - run: task build-frontend + - run: task build:frontend - name: Login to Docker Hub uses: docker/login-action@v3 with: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d6e694f1..311a2fd7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -86,7 +86,7 @@ task docs To start a local server on port `8000` to view the built documentation: ```bash -task docs-serve +task docs:serve ``` ## Release diff --git a/Taskfile.yml b/Taskfile.yml index 9721317f..855507bc 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -10,14 +10,14 @@ vars: -v ./CONTRIBUTING.md:/docs/docs/contributing.md tasks: - build-frontend: + build:frontend: desc: Build frontend assets dir: frontend cmds: - pnpm install --frozen-lockfile - pnpm run build - build-backend: + build:backend: desc: Build backend binary cmds: - go build -ldflags='-s -w -X "github.com/filebrowser/filebrowser/v2/version.Version={{.VERSION}}" -X "github.com/filebrowser/filebrowser/v2/version.CommitSHA={{.GIT_COMMIT}}"' -o filebrowser . @@ -30,16 +30,16 @@ tasks: build: desc: Build both frontend and backend cmds: - - task: build-frontend - - task: build-backend + - task: build:frontend + - task: build:backend - release-make: + release:make: internal: true prompt: Do you wish to proceed? cmds: - pnpm dlx commit-and-tag-version -s - release-dry-run: + release:dry-run: internal: true cmds: - pnpm dlx commit-and-tag-version --dry-run --skip @@ -47,10 +47,20 @@ tasks: release: desc: Create a new release cmds: - - task: release-dry-run - - task: release-make + - task: docs:cli:generate + - git add www/docs/cli + - task: release:dry-run + - task: release:make - docs-image-make: + docs:cli:generate: + cmds: + - rm -rf www/docs/cli + - mkdir -p www/docs/cli + - go run . docs + generates: + - www/docs/cli + + docs:docker:generate: internal: true cmds: - docker build -f www/Dockerfile --progress=plain -t filebrowser.site www @@ -59,11 +69,11 @@ tasks: desc: Generate documentation cmds: - rm -rf www/public - - task: docs-image-make + - task: docs:docker:generate - docker run --rm {{.SITE_DOCKER_FLAGS}} filebrowser.site build -d "public" - docs-serve: + docs:serve: desc: Serve documentation cmds: - - task: docs-image-make + - task: docs:docker:generate - docker run --rm -it -p 8000:8000 {{.SITE_DOCKER_FLAGS}} filebrowser.site diff --git a/cmd/docs.go b/cmd/docs.go index 90e5a259..7f4f536e 100644 --- a/cmd/docs.go +++ b/cmd/docs.go @@ -3,36 +3,18 @@ package cmd import ( "bytes" "fmt" - "io" "os" - "path/filepath" - "sort" + "path" + "regexp" "strings" "github.com/spf13/cobra" - "github.com/spf13/pflag" + "github.com/spf13/cobra/doc" ) func init() { rootCmd.AddCommand(docsCmd) - docsCmd.Flags().StringP("path", "p", "./docs", "path to save the docs") -} - -func printToc(names []string) { - for i, name := range names { - name = strings.TrimSuffix(name, filepath.Ext(name)) - name = strings.ReplaceAll(name, "-", " ") - names[i] = name - } - - sort.Strings(names) - - toc := "" - for _, name := range names { - toc += "* [" + name + "](cli/" + strings.ReplaceAll(name, " ", "-") + ".md)\n" - } - - fmt.Println(toc) + docsCmd.Flags().String("out", "www/docs/cli", "directory to write the docs to") } var docsCmd = &cobra.Command{ @@ -40,115 +22,61 @@ var docsCmd = &cobra.Command{ Hidden: true, Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, _ []string) error { - dir, err := getString(cmd.Flags(), "path") + outputDir, err := cmd.Flags().GetString("out") if err != nil { return err } - err = generateDocs(rootCmd, dir) + tempDir, err := os.MkdirTemp(os.TempDir(), "filebrowser-docs-") if err != nil { return err } - names := []string{} + defer os.RemoveAll(tempDir) - err = filepath.Walk(dir, func(_ string, info os.FileInfo, err error) error { - if err != nil || info.IsDir() { - return err - } + rootCmd.Root().DisableAutoGenTag = true - if !strings.HasPrefix(info.Name(), "filebrowser") { - return nil - } - - names = append(names, info.Name()) - return nil + err = doc.GenMarkdownTreeCustom(cmd.Root(), tempDir, func(f string) string { + return "" + }, func(s string) string { + return s }) if err != nil { return err } - printToc(names) - return nil - }, -} - -func generateDocs(cmd *cobra.Command, dir string) error { - for _, c := range cmd.Commands() { - if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() { - continue - } - - err := generateDocs(c, dir) + entries, err := os.ReadDir(tempDir) if err != nil { return err } - } - basename := strings.ReplaceAll(cmd.CommandPath(), " ", "-") + ".md" - filename := filepath.Join(dir, basename) - f, err := os.Create(filename) - if err != nil { - return err - } - defer f.Close() - return generateMarkdown(cmd, f) -} - -func generateMarkdown(cmd *cobra.Command, w io.Writer) error { - cmd.InitDefaultHelpCmd() - cmd.InitDefaultHelpFlag() - - buf := new(bytes.Buffer) - name := cmd.CommandPath() - - short := cmd.Short - long := cmd.Long - if long == "" { - long = short - } - - buf.WriteString("---\ndescription: " + short + "\n---\n\n") - buf.WriteString("# " + name + "\n\n") - buf.WriteString("## Synopsis\n\n") - buf.WriteString(long + "\n\n") - - if cmd.Runnable() { - _, _ = fmt.Fprintf(buf, "```\n%s\n```\n\n", cmd.UseLine()) - } - - if cmd.Example != "" { - buf.WriteString("## Examples\n\n") - _, _ = fmt.Fprintf(buf, "```\n%s\n```\n\n", cmd.Example) - } - - printOptions(buf, cmd) - _, err := buf.WriteTo(w) - return err -} - -func generateFlagsTable(fs *pflag.FlagSet, buf io.StringWriter) { - _, _ = buf.WriteString("| Name | Shorthand | Usage |\n") - _, _ = buf.WriteString("|------|-----------|-------|\n") - - fs.VisitAll(func(f *pflag.Flag) { - _, _ = buf.WriteString("|" + f.Name + "|" + f.Shorthand + "|" + f.Usage + "|\n") - }) -} - -func printOptions(buf *bytes.Buffer, cmd *cobra.Command) { - flags := cmd.NonInheritedFlags() - flags.SetOutput(buf) - if flags.HasAvailableFlags() { - buf.WriteString("## Options\n\n") - generateFlagsTable(flags, buf) - buf.WriteString("\n") - } - - parentFlags := cmd.InheritedFlags() - parentFlags.SetOutput(buf) - if parentFlags.HasAvailableFlags() { - buf.WriteString("### Inherited\n\n") - generateFlagsTable(parentFlags, buf) - buf.WriteString("\n") - } + headerRegex := regexp.MustCompile(`(?m)^(##)(.*)$`) + linkRegex := regexp.MustCompile(`\(filebrowser(.*)\.md\)`) + + fmt.Println("Generated Documents:") + + for _, entry := range entries { + srcPath := path.Join(tempDir, entry.Name()) + dstPath := path.Join(outputDir, strings.ReplaceAll(entry.Name(), "_", "-")) + + data, err := os.ReadFile(srcPath) + if err != nil { + return err + } + + data = headerRegex.ReplaceAll(data, []byte("#$2")) + data = linkRegex.ReplaceAllFunc(data, func(b []byte) []byte { + return bytes.ReplaceAll(b, []byte("_"), []byte("-")) + }) + data = bytes.ReplaceAll(data, []byte("## SEE ALSO"), []byte("## See Also")) + + err = os.WriteFile(dstPath, data, 0666) + if err != nil { + return err + } + + fmt.Println("- " + dstPath) + } + + return nil + }, } diff --git a/go.mod b/go.mod index 724b0c8f..47da2619 100644 --- a/go.mod +++ b/go.mod @@ -38,6 +38,7 @@ require ( github.com/bodgit/plumbing v1.3.0 // indirect github.com/bodgit/sevenzip v1.6.1 // indirect github.com/bodgit/windows v1.0.1 // indirect + github.com/cpuguy83/go-md2man/v2 v2.0.6 // indirect github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect github.com/dsnet/compress v0.0.2-0.20230904184137-39efe44ab707 // indirect github.com/dsoprea/go-logging v0.0.0-20200710184922-b02d349568dd // indirect @@ -60,6 +61,7 @@ require ( github.com/pierrec/lz4/v4 v4.1.22 // indirect github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect + github.com/russross/blackfriday/v2 v2.1.0 // indirect github.com/sagikazarmark/locafero v0.11.0 // indirect github.com/sorairolake/lzip-go v0.3.8 // indirect github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect diff --git a/go.sum b/go.sum index 0b374007..c6b0e41b 100644 --- a/go.sum +++ b/go.sum @@ -47,6 +47,7 @@ github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWR github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI= github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU= github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw= +github.com/cpuguy83/go-md2man/v2 v2.0.6 h1:XJtiaUW6dEEqVuZiMTn1ldk455QWwEIsMIJlo5vtkx0= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= @@ -196,6 +197,7 @@ github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1: github.com/rogpeppe/go-internal v1.3.0/go.mod h1:M8bDsm7K2OlrFYOpmOWEs/qY81heoFRclV5y23lUDJ4= github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8= github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs= +github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/rwcarlsen/goexif v0.0.0-20190401172101-9e8deecbddbd/go.mod h1:hPqNNc0+uJM6H+SuU8sEs5K5IQeKccPqeSjfgcKGgPk= github.com/sagikazarmark/locafero v0.11.0 h1:1iurJgmM9G3PA/I+wWYIOw/5SyBtxapeHDcg+AAIFXc= diff --git a/www/docs/cli/filebrowser-cmds-add.md b/www/docs/cli/filebrowser-cmds-add.md new file mode 100644 index 00000000..fc064ea9 --- /dev/null +++ b/www/docs/cli/filebrowser-cmds-add.md @@ -0,0 +1,29 @@ +# filebrowser cmds add + +Add a command to run on a specific event + +## Synopsis + +Add a command to run on a specific event. + +``` +filebrowser cmds add [flags] +``` + +## Options + +``` + -h, --help help for add +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser cmds](filebrowser-cmds.md) - Command runner management utility + diff --git a/www/docs/cli/filebrowser-cmds-ls.md b/www/docs/cli/filebrowser-cmds-ls.md new file mode 100644 index 00000000..136df2e8 --- /dev/null +++ b/www/docs/cli/filebrowser-cmds-ls.md @@ -0,0 +1,30 @@ +# filebrowser cmds ls + +List all commands for each event + +## Synopsis + +List all commands for each event. + +``` +filebrowser cmds ls [flags] +``` + +## Options + +``` + -e, --event string event name, without 'before' or 'after' + -h, --help help for ls +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser cmds](filebrowser-cmds.md) - Command runner management utility + diff --git a/www/docs/cli/filebrowser-cmds-rm.md b/www/docs/cli/filebrowser-cmds-rm.md new file mode 100644 index 00000000..837813b9 --- /dev/null +++ b/www/docs/cli/filebrowser-cmds-rm.md @@ -0,0 +1,37 @@ +# filebrowser cmds rm + +Removes a command from an event hooker + +## Synopsis + +Removes a command from an event hooker. The provided index +is the same that's printed when you run 'cmds ls'. Note +that after each removal/addition, the index of the +commands change. So be careful when removing them after each +other. + +You can also specify an optional parameter (index_end) so +you can remove all commands from 'index' to 'index_end', +including 'index_end'. + +``` +filebrowser cmds rm [index_end] [flags] +``` + +## Options + +``` + -h, --help help for rm +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser cmds](filebrowser-cmds.md) - Command runner management utility + diff --git a/www/docs/cli/filebrowser-cmds.md b/www/docs/cli/filebrowser-cmds.md new file mode 100644 index 00000000..bc61418b --- /dev/null +++ b/www/docs/cli/filebrowser-cmds.md @@ -0,0 +1,28 @@ +# filebrowser cmds + +Command runner management utility + +## Synopsis + +Command runner management utility. + +## Options + +``` + -h, --help help for cmds +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser](filebrowser.md) - A stylish web-based file browser +* [filebrowser cmds add](filebrowser-cmds-add.md) - Add a command to run on a specific event +* [filebrowser cmds ls](filebrowser-cmds-ls.md) - List all commands for each event +* [filebrowser cmds rm](filebrowser-cmds-rm.md) - Removes a command from an event hooker + diff --git a/www/docs/cli/filebrowser-completion-bash.md b/www/docs/cli/filebrowser-completion-bash.md new file mode 100644 index 00000000..e4c8963a --- /dev/null +++ b/www/docs/cli/filebrowser-completion-bash.md @@ -0,0 +1,50 @@ +# filebrowser completion bash + +Generate the autocompletion script for bash + +## Synopsis + +Generate the autocompletion script for the bash shell. + +This script depends on the 'bash-completion' package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + + source <(filebrowser completion bash) + +To load completions for every new session, execute once: + +### Linux: + + filebrowser completion bash > /etc/bash_completion.d/filebrowser + +### macOS: + + filebrowser completion bash > $(brew --prefix)/etc/bash_completion.d/filebrowser + +You will need to start a new shell for this setup to take effect. + + +``` +filebrowser completion bash +``` + +## Options + +``` + -h, --help help for bash + --no-descriptions disable completion descriptions +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser completion](filebrowser-completion.md) - Generate the autocompletion script for the specified shell + diff --git a/www/docs/cli/filebrowser-completion-fish.md b/www/docs/cli/filebrowser-completion-fish.md new file mode 100644 index 00000000..e8297aa1 --- /dev/null +++ b/www/docs/cli/filebrowser-completion-fish.md @@ -0,0 +1,41 @@ +# filebrowser completion fish + +Generate the autocompletion script for fish + +## Synopsis + +Generate the autocompletion script for the fish shell. + +To load completions in your current shell session: + + filebrowser completion fish | source + +To load completions for every new session, execute once: + + filebrowser completion fish > ~/.config/fish/completions/filebrowser.fish + +You will need to start a new shell for this setup to take effect. + + +``` +filebrowser completion fish [flags] +``` + +## Options + +``` + -h, --help help for fish + --no-descriptions disable completion descriptions +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser completion](filebrowser-completion.md) - Generate the autocompletion script for the specified shell + diff --git a/www/docs/cli/filebrowser-completion-powershell.md b/www/docs/cli/filebrowser-completion-powershell.md new file mode 100644 index 00000000..21f84c4c --- /dev/null +++ b/www/docs/cli/filebrowser-completion-powershell.md @@ -0,0 +1,38 @@ +# filebrowser completion powershell + +Generate the autocompletion script for powershell + +## Synopsis + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + + filebrowser completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, add the output of the above command +to your powershell profile. + + +``` +filebrowser completion powershell [flags] +``` + +## Options + +``` + -h, --help help for powershell + --no-descriptions disable completion descriptions +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser completion](filebrowser-completion.md) - Generate the autocompletion script for the specified shell + diff --git a/www/docs/cli/filebrowser-completion-zsh.md b/www/docs/cli/filebrowser-completion-zsh.md new file mode 100644 index 00000000..f54794b0 --- /dev/null +++ b/www/docs/cli/filebrowser-completion-zsh.md @@ -0,0 +1,52 @@ +# filebrowser completion zsh + +Generate the autocompletion script for zsh + +## Synopsis + +Generate the autocompletion script for the zsh shell. + +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: + + echo "autoload -U compinit; compinit" >> ~/.zshrc + +To load completions in your current shell session: + + source <(filebrowser completion zsh) + +To load completions for every new session, execute once: + +### Linux: + + filebrowser completion zsh > "${fpath[1]}/_filebrowser" + +### macOS: + + filebrowser completion zsh > $(brew --prefix)/share/zsh/site-functions/_filebrowser + +You will need to start a new shell for this setup to take effect. + + +``` +filebrowser completion zsh [flags] +``` + +## Options + +``` + -h, --help help for zsh + --no-descriptions disable completion descriptions +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser completion](filebrowser-completion.md) - Generate the autocompletion script for the specified shell + diff --git a/www/docs/cli/filebrowser-completion.md b/www/docs/cli/filebrowser-completion.md new file mode 100644 index 00000000..b2c6bdc1 --- /dev/null +++ b/www/docs/cli/filebrowser-completion.md @@ -0,0 +1,31 @@ +# filebrowser completion + +Generate the autocompletion script for the specified shell + +## Synopsis + +Generate the autocompletion script for filebrowser for the specified shell. +See each sub-command's help for details on how to use the generated script. + + +## Options + +``` + -h, --help help for completion +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser](filebrowser.md) - A stylish web-based file browser +* [filebrowser completion bash](filebrowser-completion-bash.md) - Generate the autocompletion script for bash +* [filebrowser completion fish](filebrowser-completion-fish.md) - Generate the autocompletion script for fish +* [filebrowser completion powershell](filebrowser-completion-powershell.md) - Generate the autocompletion script for powershell +* [filebrowser completion zsh](filebrowser-completion-zsh.md) - Generate the autocompletion script for zsh + diff --git a/www/docs/cli/filebrowser-config-cat.md b/www/docs/cli/filebrowser-config-cat.md new file mode 100644 index 00000000..952580fd --- /dev/null +++ b/www/docs/cli/filebrowser-config-cat.md @@ -0,0 +1,29 @@ +# filebrowser config cat + +Prints the configuration + +## Synopsis + +Prints the configuration. + +``` +filebrowser config cat [flags] +``` + +## Options + +``` + -h, --help help for cat +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser config](filebrowser-config.md) - Configuration management utility + diff --git a/www/docs/cli/filebrowser-config-export.md b/www/docs/cli/filebrowser-config-export.md new file mode 100644 index 00000000..141d4e8e --- /dev/null +++ b/www/docs/cli/filebrowser-config-export.md @@ -0,0 +1,31 @@ +# filebrowser config export + +Export the configuration to a file + +## Synopsis + +Export the configuration to a file. The path must be for a +json or yaml file. This exported configuration can be changed, +and imported again with 'config import' command. + +``` +filebrowser config export [flags] +``` + +## Options + +``` + -h, --help help for export +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser config](filebrowser-config.md) - Configuration management utility + diff --git a/www/docs/cli/filebrowser-config-import.md b/www/docs/cli/filebrowser-config-import.md new file mode 100644 index 00000000..871da341 --- /dev/null +++ b/www/docs/cli/filebrowser-config-import.md @@ -0,0 +1,36 @@ +# filebrowser config import + +Import a configuration file + +## Synopsis + +Import a configuration file. This will replace all the existing +configuration. Can be used with or without unexisting databases. + +If used with a nonexisting database, a key will be generated +automatically. Otherwise the key will be kept the same as in the +database. + +The path must be for a json or yaml file. + +``` +filebrowser config import [flags] +``` + +## Options + +``` + -h, --help help for import +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser config](filebrowser-config.md) - Configuration management utility + diff --git a/www/docs/cli/filebrowser-config-init.md b/www/docs/cli/filebrowser-config-init.md new file mode 100644 index 00000000..f317c9a0 --- /dev/null +++ b/www/docs/cli/filebrowser-config-init.md @@ -0,0 +1,87 @@ +# filebrowser config init + +Initialize a new database + +## Synopsis + +Initialize a new database to use with File Browser. All of +this options can be changed in the future with the command +'filebrowser config set'. The user related flags apply +to the defaults when creating new users and you don't +override the options. + +``` +filebrowser config init [flags] +``` + +## Options + +``` + --aceEditorTheme string ace editor's syntax highlighting theme for users + -a, --address string address to listen on (default "127.0.0.1") + --auth.command string command for auth.method=hook + --auth.header string HTTP header for auth.method=proxy + --auth.method string authentication type (default "json") + -b, --baseurl string base url + --branding.color string set the theme color + --branding.disableExternal disable external links such as GitHub links + --branding.disableUsedPercentage disable used disk percentage graph + --branding.files string path to directory with images and custom styles + --branding.name string replace 'File Browser' by this name + --branding.theme string set the theme + --cache-dir string file cache directory (disabled if empty) + -t, --cert string tls certificate + --commands strings a list of the commands a user can execute + --create-user-dir generate user's home directory automatically + --dateFormat use date format (true for absolute time, false for relative) + --dir-mode string Mode bits that new directories are created with (default "0o750") + --disable-exec disables Command Runner feature (default true) + --disable-preview-resize disable resize of image previews + --disable-thumbnails disable image thumbnails + --disable-type-detection-by-header disables type detection by reading file headers + --file-mode string Mode bits that new files are created with (default "0o640") + -h, --help help for init + --hide-login-button hide login button from public pages + --hideDotfiles hide dotfiles + --img-processors int image processors count (default 4) + -k, --key string tls key + --locale string locale for users (default "en") + --lockPassword lock password + -l, --log string log output (default "stdout") + --minimum-password-length uint minimum password length for new users (default 12) + --perm.admin admin perm for users + --perm.create create perm for users (default true) + --perm.delete delete perm for users (default true) + --perm.download download perm for users (default true) + --perm.execute execute perm for users (default true) + --perm.modify modify perm for users (default true) + --perm.rename rename perm for users (default true) + --perm.share share perm for users (default true) + -p, --port string port to listen on (default "8080") + --recaptcha.host string use another host for ReCAPTCHA. recaptcha.net might be useful in China (default "https://www.google.com") + --recaptcha.key string ReCaptcha site key + --recaptcha.secret string ReCaptcha secret + -r, --root string root to prepend to relative paths (default ".") + --scope string scope for users (default ".") + --shell string shell command to which other commands should be appended + -s, --signup allow users to signup + --singleClick use single clicks only + --socket string socket to listen to (cannot be used with address, port, cert nor key flags) + --socket-perm uint32 unix socket file permissions (default 438) + --sorting.asc sorting by ascending order + --sorting.by string sorting mode (name, size or modified) (default "name") + --token-expiration-time string user session timeout (default "2h") + --viewMode string view mode for users (default "list") +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser config](filebrowser-config.md) - Configuration management utility + diff --git a/www/docs/cli/filebrowser-config-set.md b/www/docs/cli/filebrowser-config-set.md new file mode 100644 index 00000000..a396ab13 --- /dev/null +++ b/www/docs/cli/filebrowser-config-set.md @@ -0,0 +1,84 @@ +# filebrowser config set + +Updates the configuration + +## Synopsis + +Updates the configuration. Set the flags for the options +you want to change. Other options will remain unchanged. + +``` +filebrowser config set [flags] +``` + +## Options + +``` + --aceEditorTheme string ace editor's syntax highlighting theme for users + -a, --address string address to listen on (default "127.0.0.1") + --auth.command string command for auth.method=hook + --auth.header string HTTP header for auth.method=proxy + --auth.method string authentication type (default "json") + -b, --baseurl string base url + --branding.color string set the theme color + --branding.disableExternal disable external links such as GitHub links + --branding.disableUsedPercentage disable used disk percentage graph + --branding.files string path to directory with images and custom styles + --branding.name string replace 'File Browser' by this name + --branding.theme string set the theme + --cache-dir string file cache directory (disabled if empty) + -t, --cert string tls certificate + --commands strings a list of the commands a user can execute + --create-user-dir generate user's home directory automatically + --dateFormat use date format (true for absolute time, false for relative) + --dir-mode string Mode bits that new directories are created with (default "0o750") + --disable-exec disables Command Runner feature (default true) + --disable-preview-resize disable resize of image previews + --disable-thumbnails disable image thumbnails + --disable-type-detection-by-header disables type detection by reading file headers + --file-mode string Mode bits that new files are created with (default "0o640") + -h, --help help for set + --hide-login-button hide login button from public pages + --hideDotfiles hide dotfiles + --img-processors int image processors count (default 4) + -k, --key string tls key + --locale string locale for users (default "en") + --lockPassword lock password + -l, --log string log output (default "stdout") + --minimum-password-length uint minimum password length for new users (default 12) + --perm.admin admin perm for users + --perm.create create perm for users (default true) + --perm.delete delete perm for users (default true) + --perm.download download perm for users (default true) + --perm.execute execute perm for users (default true) + --perm.modify modify perm for users (default true) + --perm.rename rename perm for users (default true) + --perm.share share perm for users (default true) + -p, --port string port to listen on (default "8080") + --recaptcha.host string use another host for ReCAPTCHA. recaptcha.net might be useful in China (default "https://www.google.com") + --recaptcha.key string ReCaptcha site key + --recaptcha.secret string ReCaptcha secret + -r, --root string root to prepend to relative paths (default ".") + --scope string scope for users (default ".") + --shell string shell command to which other commands should be appended + -s, --signup allow users to signup + --singleClick use single clicks only + --socket string socket to listen to (cannot be used with address, port, cert nor key flags) + --socket-perm uint32 unix socket file permissions (default 438) + --sorting.asc sorting by ascending order + --sorting.by string sorting mode (name, size or modified) (default "name") + --token-expiration-time string user session timeout (default "2h") + --viewMode string view mode for users (default "list") +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser config](filebrowser-config.md) - Configuration management utility + diff --git a/www/docs/cli/filebrowser-config.md b/www/docs/cli/filebrowser-config.md new file mode 100644 index 00000000..b87dbf07 --- /dev/null +++ b/www/docs/cli/filebrowser-config.md @@ -0,0 +1,30 @@ +# filebrowser config + +Configuration management utility + +## Synopsis + +Configuration management utility. + +## Options + +``` + -h, --help help for config +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser](filebrowser.md) - A stylish web-based file browser +* [filebrowser config cat](filebrowser-config-cat.md) - Prints the configuration +* [filebrowser config export](filebrowser-config-export.md) - Export the configuration to a file +* [filebrowser config import](filebrowser-config-import.md) - Import a configuration file +* [filebrowser config init](filebrowser-config-init.md) - Initialize a new database +* [filebrowser config set](filebrowser-config-set.md) - Updates the configuration + diff --git a/www/docs/cli/filebrowser-hash.md b/www/docs/cli/filebrowser-hash.md new file mode 100644 index 00000000..9d480547 --- /dev/null +++ b/www/docs/cli/filebrowser-hash.md @@ -0,0 +1,29 @@ +# filebrowser hash + +Hashes a password + +## Synopsis + +Hashes a password using bcrypt algorithm. + +``` +filebrowser hash [flags] +``` + +## Options + +``` + -h, --help help for hash +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser](filebrowser.md) - A stylish web-based file browser + diff --git a/www/docs/cli/filebrowser-rules-add.md b/www/docs/cli/filebrowser-rules-add.md new file mode 100644 index 00000000..2fd2efaf --- /dev/null +++ b/www/docs/cli/filebrowser-rules-add.md @@ -0,0 +1,33 @@ +# filebrowser rules add + +Add a global rule or user rule + +## Synopsis + +Add a global rule or user rule. + +``` +filebrowser rules add [flags] +``` + +## Options + +``` + -a, --allow indicates this is an allow rule + -h, --help help for add + -r, --regex indicates this is a regex rule +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") + -i, --id uint id of user to which the rules apply + -u, --username string username of user to which the rules apply +``` + +## See Also + +* [filebrowser rules](filebrowser-rules.md) - Rules management utility + diff --git a/www/docs/cli/filebrowser-rules-ls.md b/www/docs/cli/filebrowser-rules-ls.md new file mode 100644 index 00000000..8a9cc6eb --- /dev/null +++ b/www/docs/cli/filebrowser-rules-ls.md @@ -0,0 +1,31 @@ +# filebrowser rules ls + +List global rules or user specific rules + +## Synopsis + +List global rules or user specific rules. + +``` +filebrowser rules ls [flags] +``` + +## Options + +``` + -h, --help help for ls +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") + -i, --id uint id of user to which the rules apply + -u, --username string username of user to which the rules apply +``` + +## See Also + +* [filebrowser rules](filebrowser-rules.md) - Rules management utility + diff --git a/www/docs/cli/filebrowser-rules-rm.md b/www/docs/cli/filebrowser-rules-rm.md new file mode 100644 index 00000000..1870afbb --- /dev/null +++ b/www/docs/cli/filebrowser-rules-rm.md @@ -0,0 +1,40 @@ +# filebrowser rules rm + +Remove a global rule or user rule + +## Synopsis + +Remove a global rule or user rule. The provided index +is the same that's printed when you run 'rules ls'. Note +that after each removal/addition, the index of the +commands change. So be careful when removing them after each +other. + +You can also specify an optional parameter (index_end) so +you can remove all commands from 'index' to 'index_end', +including 'index_end'. + +``` +filebrowser rules rm [index_end] [flags] +``` + +## Options + +``` + -h, --help help for rm + --index uint index of rule to remove +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") + -i, --id uint id of user to which the rules apply + -u, --username string username of user to which the rules apply +``` + +## See Also + +* [filebrowser rules](filebrowser-rules.md) - Rules management utility + diff --git a/www/docs/cli/filebrowser-rules.md b/www/docs/cli/filebrowser-rules.md new file mode 100644 index 00000000..cc8386d0 --- /dev/null +++ b/www/docs/cli/filebrowser-rules.md @@ -0,0 +1,34 @@ +# filebrowser rules + +Rules management utility + +## Synopsis + +On each subcommand you'll have available at least two flags: +"username" and "id". You must either set only one of them +or none. If you set one of them, the command will apply to +an user, otherwise it will be applied to the global set or +rules. + +## Options + +``` + -h, --help help for rules + -i, --id uint id of user to which the rules apply + -u, --username string username of user to which the rules apply +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser](filebrowser.md) - A stylish web-based file browser +* [filebrowser rules add](filebrowser-rules-add.md) - Add a global rule or user rule +* [filebrowser rules ls](filebrowser-rules-ls.md) - List global rules or user specific rules +* [filebrowser rules rm](filebrowser-rules-rm.md) - Remove a global rule or user rule + diff --git a/www/docs/cli/filebrowser-users-add.md b/www/docs/cli/filebrowser-users-add.md new file mode 100644 index 00000000..c6c5b53d --- /dev/null +++ b/www/docs/cli/filebrowser-users-add.md @@ -0,0 +1,48 @@ +# filebrowser users add + +Create a new user + +## Synopsis + +Create a new user and add it to the database. + +``` +filebrowser users add [flags] +``` + +## Options + +``` + --aceEditorTheme string ace editor's syntax highlighting theme for users + --commands strings a list of the commands a user can execute + --dateFormat use date format (true for absolute time, false for relative) + -h, --help help for add + --hideDotfiles hide dotfiles + --locale string locale for users (default "en") + --lockPassword lock password + --perm.admin admin perm for users + --perm.create create perm for users (default true) + --perm.delete delete perm for users (default true) + --perm.download download perm for users (default true) + --perm.execute execute perm for users (default true) + --perm.modify modify perm for users (default true) + --perm.rename rename perm for users (default true) + --perm.share share perm for users (default true) + --scope string scope for users (default ".") + --singleClick use single clicks only + --sorting.asc sorting by ascending order + --sorting.by string sorting mode (name, size or modified) (default "name") + --viewMode string view mode for users (default "list") +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser users](filebrowser-users.md) - Users management utility + diff --git a/www/docs/cli/filebrowser-users-export.md b/www/docs/cli/filebrowser-users-export.md new file mode 100644 index 00000000..e513a453 --- /dev/null +++ b/www/docs/cli/filebrowser-users-export.md @@ -0,0 +1,30 @@ +# filebrowser users export + +Export all users to a file. + +## Synopsis + +Export all users to a json or yaml file. Please indicate the +path to the file where you want to write the users. + +``` +filebrowser users export [flags] +``` + +## Options + +``` + -h, --help help for export +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser users](filebrowser-users.md) - Users management utility + diff --git a/www/docs/cli/filebrowser-users-find.md b/www/docs/cli/filebrowser-users-find.md new file mode 100644 index 00000000..19ed3924 --- /dev/null +++ b/www/docs/cli/filebrowser-users-find.md @@ -0,0 +1,29 @@ +# filebrowser users find + +Find a user by username or id + +## Synopsis + +Find a user by username or id. If no flag is set, all users will be printed. + +``` +filebrowser users find [flags] +``` + +## Options + +``` + -h, --help help for find +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser users](filebrowser-users.md) - Users management utility + diff --git a/www/docs/cli/filebrowser-users-import.md b/www/docs/cli/filebrowser-users-import.md new file mode 100644 index 00000000..efc185fc --- /dev/null +++ b/www/docs/cli/filebrowser-users-import.md @@ -0,0 +1,34 @@ +# filebrowser users import + +Import users from a file + +## Synopsis + +Import users from a file. The path must be for a json or yaml +file. You can use this command to import new users to your +installation. For that, just don't place their ID on the files +list or set it to 0. + +``` +filebrowser users import [flags] +``` + +## Options + +``` + -h, --help help for import + --overwrite overwrite users with the same id/username combo + --replace replace the entire user base +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser users](filebrowser-users.md) - Users management utility + diff --git a/www/docs/cli/filebrowser-users-ls.md b/www/docs/cli/filebrowser-users-ls.md new file mode 100644 index 00000000..59a4f8fe --- /dev/null +++ b/www/docs/cli/filebrowser-users-ls.md @@ -0,0 +1,25 @@ +# filebrowser users ls + +List all users. + +``` +filebrowser users ls [flags] +``` + +## Options + +``` + -h, --help help for ls +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser users](filebrowser-users.md) - Users management utility + diff --git a/www/docs/cli/filebrowser-users-rm.md b/www/docs/cli/filebrowser-users-rm.md new file mode 100644 index 00000000..0e3b3035 --- /dev/null +++ b/www/docs/cli/filebrowser-users-rm.md @@ -0,0 +1,29 @@ +# filebrowser users rm + +Delete a user by username or id + +## Synopsis + +Delete a user by username or id + +``` +filebrowser users rm [flags] +``` + +## Options + +``` + -h, --help help for rm +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser users](filebrowser-users.md) - Users management utility + diff --git a/www/docs/cli/filebrowser-users-update.md b/www/docs/cli/filebrowser-users-update.md new file mode 100644 index 00000000..996bdac7 --- /dev/null +++ b/www/docs/cli/filebrowser-users-update.md @@ -0,0 +1,51 @@ +# filebrowser users update + +Updates an existing user + +## Synopsis + +Updates an existing user. Set the flags for the +options you want to change. + +``` +filebrowser users update [flags] +``` + +## Options + +``` + --aceEditorTheme string ace editor's syntax highlighting theme for users + --commands strings a list of the commands a user can execute + --dateFormat use date format (true for absolute time, false for relative) + -h, --help help for update + --hideDotfiles hide dotfiles + --locale string locale for users (default "en") + --lockPassword lock password + -p, --password string new password + --perm.admin admin perm for users + --perm.create create perm for users (default true) + --perm.delete delete perm for users (default true) + --perm.download download perm for users (default true) + --perm.execute execute perm for users (default true) + --perm.modify modify perm for users (default true) + --perm.rename rename perm for users (default true) + --perm.share share perm for users (default true) + --scope string scope for users (default ".") + --singleClick use single clicks only + --sorting.asc sorting by ascending order + --sorting.by string sorting mode (name, size or modified) (default "name") + -u, --username string new username + --viewMode string view mode for users (default "list") +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser users](filebrowser-users.md) - Users management utility + diff --git a/www/docs/cli/filebrowser-users.md b/www/docs/cli/filebrowser-users.md new file mode 100644 index 00000000..63d82bc1 --- /dev/null +++ b/www/docs/cli/filebrowser-users.md @@ -0,0 +1,32 @@ +# filebrowser users + +Users management utility + +## Synopsis + +Users management utility. + +## Options + +``` + -h, --help help for users +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser](filebrowser.md) - A stylish web-based file browser +* [filebrowser users add](filebrowser-users-add.md) - Create a new user +* [filebrowser users export](filebrowser-users-export.md) - Export all users to a file. +* [filebrowser users find](filebrowser-users-find.md) - Find a user by username or id +* [filebrowser users import](filebrowser-users-import.md) - Import users from a file +* [filebrowser users ls](filebrowser-users-ls.md) - List all users. +* [filebrowser users rm](filebrowser-users-rm.md) - Delete a user by username or id +* [filebrowser users update](filebrowser-users-update.md) - Updates an existing user + diff --git a/www/docs/cli/filebrowser-version.md b/www/docs/cli/filebrowser-version.md new file mode 100644 index 00000000..ec3596c5 --- /dev/null +++ b/www/docs/cli/filebrowser-version.md @@ -0,0 +1,25 @@ +# filebrowser version + +Print the version number + +``` +filebrowser version [flags] +``` + +## Options + +``` + -h, --help help for version +``` + +## Options inherited from parent commands + +``` + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") +``` + +## See Also + +* [filebrowser](filebrowser.md) - A stylish web-based file browser + diff --git a/www/docs/cli/filebrowser.md b/www/docs/cli/filebrowser.md new file mode 100644 index 00000000..a8cbe669 --- /dev/null +++ b/www/docs/cli/filebrowser.md @@ -0,0 +1,83 @@ +# filebrowser + +A stylish web-based file browser + +## Synopsis + +File Browser CLI lets you create the database to use with File Browser, +manage your users and all the configurations without accessing the +web interface. + +If you've never run File Browser, you'll need to have a database for +it. Don't worry: you don't need to setup a separate database server. +We're using Bolt DB which is a single file database and all managed +by ourselves. + +For this specific command, all the flags you have available (except +"config" for the configuration file), can be given either through +environment variables or configuration files. + +If you don't set "config", it will look for a configuration file called +.filebrowser.{json, toml, yaml, yml} in the following directories: + +- ./ +- $HOME/ +- /etc/filebrowser/ + +The precedence of the configuration values are as follows: + +- flags +- environment variables +- configuration file +- database values +- defaults + +The environment variables are prefixed by "FB_" followed by the option +name in caps. So to set "database" via an env variable, you should +set FB_DATABASE. + +Also, if the database path doesn't exist, File Browser will enter into +the quick setup mode and a new database will be bootstrapped and a new +user created with the credentials from options "username" and "password". + +``` +filebrowser [flags] +``` + +## Options + +``` + -a, --address string address to listen on (default "127.0.0.1") + -b, --baseurl string base url + --cache-dir string file cache directory (disabled if empty) + -t, --cert string tls certificate + -c, --config string config file path + -d, --database string database path (default "./filebrowser.db") + --disable-exec disables Command Runner feature (default true) + --disable-preview-resize disable resize of image previews + --disable-thumbnails disable image thumbnails + --disable-type-detection-by-header disables type detection by reading file headers + -h, --help help for filebrowser + --img-processors int image processors count (default 4) + -k, --key string tls key + -l, --log string log output (default "stdout") + --noauth use the noauth auther when using quick setup + --password string hashed password for the first user when using quick config + -p, --port string port to listen on (default "8080") + -r, --root string root to prepend to relative paths (default ".") + --socket string socket to listen to (cannot be used with address, port, cert nor key flags) + --socket-perm uint32 unix socket file permissions (default 438) + --token-expiration-time string user session timeout (default "2h") + --username string username for the first user when using quick config (default "admin") +``` + +## See Also + +* [filebrowser cmds](filebrowser-cmds.md) - Command runner management utility +* [filebrowser completion](filebrowser-completion.md) - Generate the autocompletion script for the specified shell +* [filebrowser config](filebrowser-config.md) - Configuration management utility +* [filebrowser hash](filebrowser-hash.md) - Hashes a password +* [filebrowser rules](filebrowser-rules.md) - Rules management utility +* [filebrowser users](filebrowser-users.md) - Users management utility +* [filebrowser version](filebrowser-version.md) - Print the version number + diff --git a/www/mkdocs.yml b/www/mkdocs.yml index d489dcd5..a7fb41ea 100644 --- a/www/mkdocs.yml +++ b/www/mkdocs.yml @@ -34,8 +34,6 @@ theme: features: - navigation.tabs - navigation.tabs.sticky - - navigation.sections - - navigation.expand - navigation.indexes - navigation.top - navigation.instant @@ -44,7 +42,6 @@ theme: - search.share - content.code.copy - toc.follow - - toc.integrate icon: repo: fontawesome/brands/github @@ -97,10 +94,41 @@ extra: nav: - Home: index.md - - Getting Started: + - Documentation: - Installation: installation.md - Configuration: configuration.md - Deployment: deployment.md + - Command Line Usage: + - cli/filebrowser.md + - cli/filebrowser-cmds.md + - cli/filebrowser-cmds-add.md + - cli/filebrowser-cmds-ls.md + - cli/filebrowser-cmds-rm.md + - cli/filebrowser-completion.md + - cli/filebrowser-completion-bash.md + - cli/filebrowser-completion-fish.md + - cli/filebrowser-completion-powershell.md + - cli/filebrowser-completion-zsh.md + - cli/filebrowser-config.md + - cli/filebrowser-config-cat.md + - cli/filebrowser-config-export.md + - cli/filebrowser-config-import.md + - cli/filebrowser-config-init.md + - cli/filebrowser-config-set.md + - cli/filebrowser-hash.md + - cli/filebrowser-rules.md + - cli/filebrowser-rules-add.md + - cli/filebrowser-rules-ls.md + - cli/filebrowser-rules-rm.md + - cli/filebrowser-users.md + - cli/filebrowser-users-add.md + - cli/filebrowser-users-export.md + - cli/filebrowser-users-find.md + - cli/filebrowser-users-import.md + - cli/filebrowser-users-ls.md + - cli/filebrowser-users-rm.md + - cli/filebrowser-users-update.md + - cli/filebrowser-version.md - Contributing: - Contributing: contributing.md - Code of Conduct: code-of-conduct.md