bookstackapp/website

The code for the main site, Includes BookStack docs.

website's Issues

Use BookStack for docs

It would be nice to use BookStack for the official https://www.bookstackapp.com/docs/

I understand the appeal of using something like Hugo but the better way would be to "eat your own dog food" so to speak. This will in turn lead to a better product.

Add a "BookStack in the media" page

List out any:

• YouTube video references
• Podcasts references
• Articles (Probably not installations)

Maybe social media version?

Prevent blog going down from taking out website

When the blog goes down the site is taken out since the request to the blog fails.

In reference to BookStackApp/BookStack#251

Add linuxserver.io docker link

Update install docs to include a link to https://github.com/linuxserver/docker-bookstack.

Permission granted in linuxserver/docker-bookstack#25

Internal links (to books/pages)

Hi,

We've tried to use few different documentation engines/wikis for internal documentation. They all have one major issue - If you rename a page or move it to other directory (chapter) you loose all links to it. Editing and reorganizing documentation is a nightmare. If a page becomes too big we split it to folders/chapters and we have to manually rewrite every link to this page.

My suggestion would be that the link to a page should be final, non-mutable and should be as short as possible:
https://demo.bookstackapp.com/p/123
or at least
https://demo.bookstackapp.com/b/10/p/123

The link can 301 redirect to the full page URL.

When SEO is needed the full page URL can be used, but I think most search engines get the idea of 301 redirect, so there is no need to risk page change to break the URL.

Screenshot copy error

Hi again (and sorry to bother once more),

we have random errors when pasting screenshots into an edited page of Bookstack :

The setup is :

• Ubuntu 18.04 LTS
• Apache/2.4.29 (Ubuntu)
• PHP 7.2.24-0ubuntu0.18.04.2
• Bookstack version installed with the script : https://www.bookstackapp.com/docs/admin/installation/#ubuntu-1804

.env :

• STORAGE_TYPE=local_secure

php.ini :

• post_max_size = 10M
• upload_max_filesize = 10M

custom headers :

• no changes to the default parameters so 256 MB

ACL :

• we have checked all acl on folders and it all seems correct

I have activated the APP_DEBUG=true but can't seem to find any related logs even in the laravel.log file.

Do you know what other parameters can be checked ?

Thank again.

Cheers,

Julien

Social Authentication, Google documentation inaccuracy

The section on enabling Google Authentication at https://www.bookstackapp.com/docs/admin/social-auth/ is slightly incomplete. The 'APP_URL' environment variable does not exist by default in the .env file. You have to create this. For example, an improved version of Step 9 would be:

Edit the .env file and add a variable for APP_URL. Set the APP_URL environment variable to be the same domain as you entered in step 7. So, in this example, it will be https://example.com.

I added this variable under the 'environment' section at the top

Feature request: Support mermaid

This feature request is for two things, related to the Mermaid text-to-graphics renderer. The first has much higher priority than the second.

1. Please support links to real-time rendered images, such as this:
   https://mermaid.ink/img/pako:eNpVjstqw0AMRX9FaNVC_ANeFBq7zSbQQrPzZCFsOTMk80CWCcH2v3ccb1qtxD3nCk3Yxo6xxP4W760lUTjVJkCe96ay4gb1NJyhKN7mAyv4GPgxw_7lEGGwMSUXLq-bv18lqKbjqjGodeG6bKh69r8Cz1A3R0oa0_kvOd3jDB-N-7b5_H9ihXPrs-mp7KloSaAieSq4Q8_iyXX5_WlNDKplzwbLvHYkV4MmLNmjUePPI7RYqoy8wzF1pFw7ugj5LVx-AfLqVWg?type=png

Note: Many people self-host their Mermaid renderer, so the host part of that URL may change.

2. An optional Mermaid image edit button, pointing to a live mermaid editor, such as https://mermaid.live/

Note: Many people self-host their Mermaid live editor, so the host part of that URL may change.

Don't Understand Sentence

https://github.com/BookStackApp/website/blob/main/content/docs/user/roles-and-permissions.md

"Roles can be assigned to users an admin user editing a user's profile in the "Settings > Users" area of the BookStack interface."

Identify unsplash images & update licensing

Had not realized the unsplash license had changed a while bad so does not technically fit within the MIT licensing of the project.

Our use has not been against their license, but their license is not compatible with open source, and including their content under out project's license could cause issues (Folks taking images from our repo under MIT license).

Think it'd be best to label these images in some way (Single directory, or update image names), then add a note to the readme/license file.

404 - before login when i disable public pages

I can see Popular Books, Popular Chapters and Popular Pages
will be possible protect this?

Suggestion: Add a link to the blog RSS

I shortly discovered BookStack (very nice by the way!) and wanted to be kept up-to-date with its development and releases.
Unfourtunately there was no link for RSS subscription of the blog, so I had to kind of blindly guess it:

https://www.bookstackapp.com/blog/index.xml

Maybe one could provide a link to that on the website in the future?

Document the use of page links

As per BookStackApp/BookStack#94

Documentation clarification about moving books, chapters and pages

Hi,

Trying to find out how to move a book to a different shelf I landed in this documentation page https://www.bookstackapp.com/docs/user/organising-content/

There it says "Books and chapters can be moved directly to a new chapter or book" but then explains how you can move a page or chapter (there doesn't seem to be a way to move a book, I wish there was).
Should the sentence be changed to "Pages and chapters can be moved directly to a new chapter or book" ?

could authentication memberof ldap group login？

BookStack Version: v22.07

my .env profille

I have created role

my user：
CN=azheng，OU=test,DC=test,DC=com
CN=azheng3，OU=test2,DC=test,DC=com
my group
CN=test,OU=test,DC=test,DC=com
azheng and azheng3 are in the group
when LDAP_BASE_DN="ou=test,dc=test,dc=com"
azheng can login
azheng3 can't login error messages:user or password wrong

when LDAP_BASE_DN="dc=test,dc=com"
azheng and azheng3 can login both,and two user are in this test role

the ldap group sync can't let user log through users are not in the LDAP_BASE_DN?

Add Diagrams.io integration to feature list

IMO that's a phantastic feature that should be advertised on the front page.

Language Selection for Pages

Allow pages to be created with multiple language versions. For instance, if I go to edit a page there should be a section in the right menu where I can choose which language I'd like the page to be in. Then, when viewing the page the actions menu should have a button to select a different language.

This would be exceptionally helpful for organizations with many users of different languages, or for users of products with multiple languages.

The ability to sort by language in search would be useful as well.

Document permissions setup

Basically find a place to add this general guidance somewhere:

https://gist.github.com/ssddanbrown/f0e6e850e57c419c6541dbe6c8facd4b

Suggestion documentation update LDAP_USER_FILTER in docker-compose.yml

In the LDAP Configuration page, the LDAP_USER_FILTER=(&(uid=${user})) parameter is mentioned. I would appreciate a note, that if one embeds this into a docker-compose.yml file, it has to be written like this

LDAP_USER_FILTER=(&(uid=$${user})) in order to escape the ${user} variable.

This is documented in https://stackoverflow.com/a/40619627/905817

Azure AD Authentication issue

Hi everyone,

sorry to bother but I tried to configure Azure AD authentication to Bookstack following the doc here : https://www.bookstackapp.com/docs/admin/third-party-auth/#azuread-microsoft.

Unfortunately, I get the following error after clicking on the button "Login with Microsoft Azure" in debug mode :

Client error: POST https://login.microsoftonline.com/common/oauth2/token resulted in a 401 Unauthorized response:\n
{"error":"invalid_client","error_description":"AADSTS7000215: Invalid client secret is provided.\r\nTrace ID: b4b25216-9 (truncated...)\n

From what I have read, it seems that the secret configured in Azure should be urlEncoded but I have tried various settings int .env file none of which seem to work :

example 1 : AZURE_APP_SECRET={xxxxx%3xxxxxx%5bxxxxxxxx}
example 2: AZURE_APP_SECRET='{xxxxx%3xxxxxx%5bxxxxxxxx}'
example 3: AZURE_APP_SECRET={'xxxxx%3xxxxxx%5bxxxxxxxx'}
example 4 (not urlEncoded) : AZURE_APP_SECRET={xxxxxxxxxxxxxxxxxxx}

Is there anything I am missing ?

Thank you for your help, good day to the whole team.

Julien

Hugo minify output

the generated HTML could be minified with hugo --minify to make page load times slightly faster,

Markdown Editor Docs Page Incorrect Data - Global Setting

The second sentence of the current Markdown page at https://www.bookstackapp.com/docs/user/markdown-editor/ lists the Markdown editor as being a global-setting. While it can be globally defaulted, in version 22.06.2 the editor used can be changed on a page-by-page basis.

Update facebook instructions on third party authentication page

Step 6 under "Facebook" should read:

6. Enter your base BookStack URL again into the 'Valid OAuth redirect URIs' input and save. Enter the following urls under 'Valid OAuth redirect URIs' and save, changing https://example.com to your own domain where BookStack is hosted:
   https://example.com/login/service/facebook/callback
   https://example.com/register/service/facebook/callback

Document cloudflare on our debugging page

Specifically disabling rocket loader

Add email configuration docs

User docs page: Attachments

Detail how attachments can be used, including:

• Drag and drop of videos (Related PR)
• Uploading
• Link types
• Downloading
• Opening inline
• Permission control used
• Technical section on downloading and video support,
  • Differences between storage options

Did the repository URL change?

I had some issues while upgrading from 0.13.x to 0.14.x because (somehow) my repository pointed to https://github.com/ssddanbrown/BookStack instead of https://github.com/BookStackApp/BookStack and I had to manually change this.

I think this might be something worth for the docs, when it wasn't my fault choosing the wrong repo in first place.

SELinux remark in the installation guide

Maybe it would be helpful to have some information about SELinux in the installation guide.

"Edit this Page" redirects to a 404 page

On this page - https://www.bookstackapp.com/docs/admin/commands/

Clicking on edit redirected me to - https://github.com/BookStackApp/website/blob/master/resources/content/docs/admin/commands.md which is a 404 page.

Instead it should be redirecting me to - https://github.com/BookStackApp/website/blob/master/content/docs/admin/commands.md

The resources part is extra.

Same issue on a couple of other pages that I checked. Removing resources from the URL redirects correctly.

[Suggestion] More E-Mail preferences

Hello,

I think it would be a great addition to have the option to send out e-mails if a book was added/changed.

Currently I'm sending e-mails manually from my personal Mail-Account to notify the administrators that I've added a Book or changed something important.

Add NearlyFreeSpeech as other hosting options

I just tried installing BookStack on NearlyFreeSpeech.net and it worked. The procedure is same as the Installation Manual in the documentation. With the exception of needing to use .htaccess to point document root to BookStack public folder instead of using Apache VirtualHost. So I think you can add it to the documentation. It would be great if there were more hosting options.

User docs: Getting Around

Document the various forms of navigation within the app:

• Search
• Sidebar tree
• Breadcrumbs
• Next/Previous footer links
• Shortcuts
• Links on homepage? (Recently updated etc...)

Azure AD Authentication instructions

Not sure if it was a library change or a Microsoft change, looks like the instructions for Azure AD auth don't work in v0.22.0.

3: Enter a name (‘BookStack’). Keep the ‘Application type’ as ‘Web app / API’. Set the ‘Sign-on URL’ to be the main URL to your BookStack instance.

Main url should be changed to http://example.com/login/service/azure/callback

Document session lifetime

Specifically the env option and it's unit of time, add to existing session page

Internal link generation not as expected

I'm new to using BookStack. I copied over some markdown I had on a github README, but it seems that BookStack generates tags in an unexpected way. For instance, I create a header with # Types and to link to it in my table of contents, I'm using [Types](#types), but this doesn't work. I did a page inspection and the generated tag seems to be #bkmrk-types. While this isn't a major problem, it does involve updating all of my internal links and is inconsistent with markdown in as far as I know. I inspected the raw files from your documentation in your website and saw that the markdown you are using uses the traditional [{text}](#{text}) format. Should I continue to update all of my links or is this something that is planned to be addressed?
Thanks,
James

Bookstack Doc page improvement - Page Templating

Describe the feature you'd like

Can we please have the Bookstack documentation have the Page Templating feature documented? It is in the tool, and covered in a blog post : https://www.bookstackapp.com/blog/beta-release-v0-27-0/#page-templating

But otherwise it is not documented as other functions are documented.

Describe the benefits this would bring to existing BookStack users

They can realise this feature exists, how to use it, stuff like that.

Can the goal of this request already be achieved via other means?

No?

Have you searched for an existing open/closed issue?

• I have searched for existing issues and none cover my fundemental request

How long have you been using BookStack?

0 to 6 months

Additional context

No response

Add Redis info

Once v0.9 has released

Translations of docs

Hey @ssddanbrown ,
before I begin I'd like to say: thanks for creating bookstack, it's a great software!
Also like bookstack itself, the website is super! It's simple and has all information setup in a logical, easy to navigate, pattern.

Similarly to bookstack itself that is translated into many different languages already, it would be nice to have the docs translated or at least be translatable as well.
Looking into hugo it doesn't seem like a huge task to set it up. I just wanted to check if that even is a path that you would consider. And if so if you would have any specific requirements for the implementation.

I would offer to create a german translation of the docs.

Create security mailing list

Set up a new mailchimp list specifically for security issues. Warn that there may be multiple per week. See if possible to allow user to opt-in to this when signing into blog updates.

Propose installing without dev-dependencies for production

I just noticed that in the documentation aswell as in the scripts composer install is executed. For a non-development environment i think it would be better to propose the --no-dev switch, which will skip every package that is listed in the dev-dependencies section. The composer.lock file would still be used as source for the package versions.

I just tested this, with the current release and everything went well.

Add a configuration cheatsheet

While I love BookStack as a wiki platform, the initial configuration is always very stressful for me. The documentation does indeed contain most of the available .env options, but clicking through all of the pages in order to find a specific thing is bad UX in my eyes. Adding a new cheatsheet-like page containing all available options would be a great improvement in my eyes.

An example of such a cheatsheet might be taken from the Gitea Docs.

Document REMOTE_USER authentication

Our BookStack instance does not require public access, so the simplest and most secure option for us is for the Apache webserver to handle SSO, in the same way we already have several other web-based systems. This is supported by BookStack's logical theme system, but I only found this by old bug reports and trial and error. Can this be added to the documentation? The procedure I found that worked was:

• Create a new user with your SSO email address and the Admin role
• Create /opt/bookstack/themes/remote_user/functions.php containing the code from BookStackApp/BookStack#2289 (comment), with $authVarName = 'REMOTE_USER';
• Add "APP_THEME=remote_user" to .env
• Configure the web server to use SSO for the BookStack virtual host

Document page draft management handling and controls

Right now it's not too clear on how to manage/clear drafts, and the behaviour BookStack uses for this system.
There's perhaps a UX task to make things more obvious within-app, but either way it would be good to have this kind of thing documented.

Update .env language in cache and sessions docs

The cache and sessions docs were written when the default .env had a lot more options, so it refers to updating env options that are no long in there by default. This should be updated to add/update language like other parts of our docs.

When i use npm ran dev face this isue

Update 404 page to be much nicer, and more helpful

Document export classess in hacking/customization page

https://github.com/BookStackApp/BookStack/blob/06b5a83d8f5105fceb5f44458df16a1643d7c890/resources/views/layouts/export.blade.php#L14

Conect BookStack to wordpress and woocomerce.

Hello .

It's possible to connect Bookstack and woocomerce ? If the user buy a products in my website, via the plugin woocomer, he have an acces to the documentation link at the products ?

Thanks,
Loic

How do we actually change the editor from WYSIWYG to the Markdown Editor?

The docs state the following but don't say how the editor can be swapped:

If you prefer to write in Markdown, the editor in BookStack can be changed at an instance level to use a markdown editor instead of the default WYSIWYG editor. The option to use Markdown is currently not a user setting but a global instance setting due to formatting differences between the two editors.

Where do I have to look to find the setting? I would like to change to the Markdown editor.

Add documentation for installing to Alpine Linux (and using LXC)

I'm not sure what the best way to add this is, so I've attached a markdown file (as .txt) for how I've walked through and setup a LXC container using Alpine for BookStack.
BookStackLXC_Install_Alpine.txt