Skip to main content

my BookStack hacks

this site is built using BookStack, which is great documentation software. I've modified the default BookStack setup somewhat to get away from the shelf/book/chapter/page metaphor and have sort of replaced it with my own area/section/topic/page metaphor, just to make the organization a little more generic, and cms/wiki-like. 

all the changes I've made are really kind of minimal and are outlined below: 

created this new theme folder: /var/www/bookstack/themes/robertvigil.com

copied /var/www/bookstack/resources/lang/en/entities.php to /var/www/bookstack/themes/robertvigil.com/lang/end/entities.php and changed hieararchy terms/references as follows (for all upper/lower case and plural/singular forms): "shelf" -> "area", "book" -> "section", "chapter" -> "topic", (left "page" as "page")

copied /var/www/bookstack/resources/lang/en/activities.php to /var/www/bookstack/themes/robertvigil.com/lang/end/activities.php and applied same hieararchy terms/references changes as entites.php

copied /var/www/bookstack/resources/views/pages/parts/page-display.blade.php  to var/www/bookstack/themes/robertvigil.com/pages/parts/page-display.blade.php, and commented out this line in order to, by default, not show the big page title at top of any pages (this basically turns pages into a blank slate and lets me add my own headers):

<div dir="auto">

    <!--<h1 class="break-text" id="bkmrk-page-title">{{$page->name}}</h1>-->

    <div style="clear:left;"></div>

    @if (isset($diff) && $diff)
        {!! $diff !!}
    @else
        {!! isset($page->renderedHTML) ? $page->renderedHTML : $page->html !!}
    @endif
</div>

copied /var/www/bookstack/resources/views/chapters/show.blade.php to var/www/bookstack/themes/robertvigil.com/chapters/show.blade.php and made the commented change below to decrease topic/chapter title from <h1> to <h3>:

...
<main class="content-wrap card">
        <h3 class="break-text">{{ $chapter->name }}</h3> <!-- decreased from <h1> to <h3> -->
        <div refs="entity-search@contentView" class="chapter-content">
            <div class="text-muted break-text">{!! $chapter->descriptionHtml() !!}</div>
            @if(count($pages) > 0)
                <div class="entity-list book-contents">
                    @foreach($pages as $page)
                        @include('pages.parts.list-item', ['page' => $page])
                    @endforeach
                </div>
...

added these lines to root .env file:

APP_THEME=robertvigil.com
STORAGE_TYPE=local_secure_restricted # more fine-grained permissions control, including for images, at the expense of some performance

changed role security for public role by removing all but topics (books) and pages permissions in order to greatly simplify/improve the UI experience for the public role.

BookStack is really well designed/maintained, and the overall organization and permissions systems are really well thought out. It is however intended primarily as a documentation system, hence the book metaphor used throughout. Because of how much functionality out of the box it provides, however, I was perfectly happy to take BookStack as is and modify as above for my own purposes.

Back to top