Provide a way for blind users to retrieve a page permalink

[neosonic2]

Describe the feature you'd like

As a visually impaired computer user, the current implementation of Bookstack's permalink system unfortunately provides no mechanism by which I and other blind users can retrieve a page permalink.

The page permalink documentation currently states that users must select a block of text in a page, at which time a small popup box will appear with the permalink and page ID inside. This method is perfectly well suited for sighted users, but those using screen reading software may find this doesn't work as expected.

For me in particular, I can use keyboard commands to select content on a page but if I then try to move down the page to locate the popup box, the selection is cleared and my assumption is that the popup disappears as well. This effectively means I don't have a way to get to the displayed permalink.

Other software packages with which I am familiar display the permalink on the editing interface or on the page itself (i.e. in a sidebar or aside), and I believe this approach would be universally accessible if adopted by Bookstack. However, I am open to other approaches to displaying permalink information as there may be something out there that better fits with the existing style of the user interface.

I plan to create many links between different pages of my Bookstack instance, so having the page ID or permalink would aid greatly in this effort. I currently use the VoiceOver screen reader on macOS, but Windows screen readers like NVDA and Freedom Scientific's JAWS for Windows are also most likely affected.

Describe the benefits this would bring to existing BookStack users

Bookstack is already extremely accessible to those using screen reading and other assistive technology, and implementing an alternative method for retrieving a page permalink would further improve accessibility and also make it possible to use important features such as the ability to create links between pages of content. There may also be benefits for sighted users, especially those who for whatever reason may be unable to select text in a page.

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

As far as I am aware, the goal of this feature request cannot currently be achieved (in an accessible manner) by other means.

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

I realize that solutions such as editing the visual theme system have been proposed (#2917) but I believe that greater accessibility should be something built into the core application rather than something required to be added by each end user. I also realize there may be a desire to reduce additional user interface elements when viewing pages, and to that end would posit that a button visible only to screen readers (through the use of the aria-hidden HTML attribute) could be used to mitigate this risk.

I am more than willing to aid in accessibility testing of this and other Bookstack features/feature requests if desired since a keyboard and screen reader are the only way I use my computer.

[ssddanbrown]

Thanks for the report @neosonic2.
I think i must have missed the popup box, which contains the permalink, when reviewing the system for accessibility.
Definitely something to be addressed, therefore I'm re-tagging this an accessibility bug. This box has a few features upon just the permalink, such as the ability to show the "content include" syntax tag, and the ability to jump and edit a specific box, so I think it would be ideal to make this box (and it's features) accessible instead of implementing an alternative solution for screen-reader users.

This popup box, and it's features, are quite contextual to a specific section/block of the page content. Is there an common pattern/action/shortcut for app-specific contextual actions such as this for screen-reader users? Just so we can make it easy for screen reader users to be able to use these actions/details in the context of a specific block/section. Or is the current selection method, to show the box, acceptable as long as we fix the ability to then access the popup box without it disappearing?

[neosonic2]

Thanks for all the work you’ve put in to Bookstack so far to make it accessible, and for your willingness to go even further by shoring up this accessibility concern. I think most screen reader users would probably first try to access a contextual menu to view potential options for text or other content they’ve highlighted, at least in desktop applications, but then again those applications also usually have menu bars or even keyboard shortcuts that can be used to perform actions with or view information about a selection. While Bookstack of course doesn’t have a menu bar or toolbar and isn’t a desktop application, perhaps there’s a keyboard shortcut that could be implemented to bring up the popup box when a block of content is selected on a page? I’m going down this route because screen readers and indeed their configurations vary when it comes to whether or not a user can select text and then, while still keeping that text selected, reliably find, move to, or interact with another portion of a web page; in most cases once the focus shifts away from what’s selected, the content will cease to be selected. In this way, it may be helpful to make a keyboard shortcut or other option available that doesn’t require the user to move from the selection in order to be triggered. We should probably also consider the fact that for some users, selecting a block of content on a page in Bookstack may not be possible, either temporarily or permanently. For example, sometimes VoiceOver on macOS does not let me select text on a web page, and other times it does. There doesn’t seem to be a rhyme or reason to this, and with some web pages I can never select text no matter what I do, whereas with others I am prevented from selecting text one day and then able to do so another day, without any idea as to why. All that to say that selecting content on a Bookstack page may not always be possible and so, while I recognize the popup does provide information and actions contextual to what is selected, I would like to posit that there should be a “standard” form of that popup that can apply to the page as a whole, or another way to present what would have been presented had a block been selected. For example, for my purposes I just need the permalink of a page, regardless of what content is on it, and shouldn’t have to select some content first before reviewing that information.

…

On Jan 18, 2023, at 12:03 PM, Dan Brown ***@***.***> wrote: Thanks for the report @neosonic2 <https://github.com/neosonic2>. I think i must have missed the popup box, which contains the permalink, when reviewing the system for accessibility. Definitely something to be addressed, therefore I'm re-tagging this an accessibility bug. This box has a few features upon just the permalink, such as the ability to show the "content include" syntax tag, and the ability to jump and edit a specific box, so I think it would be ideal to make this box (and it's features) accessible instead of implementing an alternative solution for screen-reader users. This popup box, and it's features, are quite contextual to a specific section/block of the page content. Is there an common pattern/action/shortcut for app-specific contextual actions such as this for screen-reader users? Just so we can make it easy for screen reader users to be able to use these actions/details in the context of a specific block/section. Or is the current selection method, to show the box, acceptable as long as we fix the ability to then access the popup box without it disappearing? — Reply to this email directly, view it on GitHub <#3975 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJDEDARJIO5RBQ3YHBJ3EDWTAO5NANCNFSM6AAAAAAT4I4PVU>. You are receiving this because you were mentioned.

[neosonic2]

While solutions are being brainstormed regarding how to retrieve a permalink specific to a selected block of content on a page, is there currently a way in Bookstack to get the base permalink for a page (regardless of selected content) that does not require the use of the pop up box? For the main reasons behind my submission of this issue, that was my goal - to get the permalink of the page I am currently viewing, without anything attached at the end.

The documentation seems to imply the only way for a user to get the page permalink, regardless of whether they want an ID to specific content attached at the end, is to select content first, but this seems counterintuitive from my limited understanding of Bookstack thus far. Is there an easy way round this requirement so that only the page permalink can be retrieved, or does this also solely require selecting content first?

[ssddanbrown]

Is there an easy way round this requirement so that only the page permalink can be retrieved, or does this also solely require selecting content first?

@neosonic2 It requires the selection of content first. To be honest I've never been to keen on the use of permalinks, they were added early and are really just used where an id-based link is really preferred. My main intent is that the normal slug-based URLs are used, as per the URL bar, since it seems more intuitive to me that URLs of the interface and those in content match. Upon that I've sided towards slug-based URLs since they describe, in URL, what they'd likely take you to upon visiting which again I think is intuitive.

There have been cases that such slug-based URLs can break, hence some users really prefer to use the id-based URLs, but the cases have been minimized via a few methods. Upon slug non-match, page revisions are checked in an attempt to find a page based on old URL slugs. Recently we added tracked references, which enables auto-updating of links to items upon URL change.

Due to my feelings above, permalink URLs have generally remained hidden in favor of always defaulting to normal non-id based URLs. I did recently think about moving to a new "best of both options" scheme in #3520 but the benefits did not seem worthwhile in comparison to the effort and disruption it would require.

[neosonic2]

Thank you for your detailed insight and explanation on this; I now understand better the system Bookstack has in place - that a straight page "permalink" (retrieved without selecting content first) is really just the existing page URL shown in the address bar. Until this point, I had been hesitant to use this URL when linking from another page because I was unsure as to the stability of such a system when I know that slugs used in URLs are generated based on book and page titles, which of course can easily be changed. As someone who often develops websites in WordPress, I am all too familiar with broken links of this (slug) style that were supposed to be permanent, but on the flip side Bookstack's current link style does improve SEO and help the user know exactly where a link will take them.

So, given that you've stated improvements to existing systems have been made to protect page links against breakage from slug changes, what would you say are the current cases in which a page link could in theory still be broken? It sounds like, especially after reading the issue you linked, such scenarios have been reduced but not fully eliminated, which is understandable. In fact, even using unique IDs as page permalinks would not truly eliminate the potential for breakage because a page could simply be deleted and re-created with the same title and content, but a different unique ID assigned by the system, and its link would still be broken through no fault of the user.

Since it's very easy for users, even those who use screen readers, to pull the current URL from the address bar, I think the only accessibility concern still at play here is pulling out the permalink when specific content is selected.

[ssddanbrown]

what would you say are the current cases in which a page link could in theory still be broken?

Off the top of my head, some examples:

• Cases where links exist outside of the platform and therefore don't automatically get updated upon URL change.
• Restoration of old page revisions may re-introduce older URLs.
• Cases where users have manually manipulated links to not align with the full BookStack base url, which hinders identification for our reference system.

Our backup-revision scanning system still may be able to handle these cases in some scenarios.

I think the only accessibility concern still at play here is pulling out the permalink when specific content is selected.

I'd want to make sure the popover contents in general are accessible, not just the permalink, since it provides a couple of additional capabilities that are specific to a section of content:

• Jumping directly to a section for editing.
• Display of the page include tag.

Have not dived too deep into this yet but, from a quick look, finding a way for this to be content-section contextual, without text selection or mouse events, is quite a challenge. At least it is without resorting to other hacks that would affect focusing and therefore potentially introduce other issues or awkward behavior.

[neosonic2]

If you wanted to implement at least a partial solution while considering ways of working around needing to select content first, you could make the existing pop up a modal dialog (if it isn't already) and use JavaScript to send focus to it immediately when it opens, after text has been selected. While not every screen reader user will be able to select text, depending on the software they are using, I believe the majority would. The issue with the current system is that the dialog appears visually but does not receive focus when it is opened, and it's difficult to keep something selected and simultaneously move down the page to find the pop up. But if this could be done automatically for the user, i.e. if they could be dropped into the pop up when it opens, that would eliminate that part of the issue. Bonus points if the user could be returned to where they were when the dialog closes.

I don't know what UI framework Bookstack's visual theme currently use, but frameworks like Bootstrap and others that implement modal dialogs usually attempt to handle focusing automatically and do a half decent job at it, but also provide JavaScript events/functions/etc. for further customization, or let the developer write their own. You might even get away with just forcing focus into the first clickable element of the dialog when it opens, rather than into the dialog itself; this is what I've done in web applications I've built when an action, such as a button click, triggers the opening of a modal dialog.

As to broader accessibility though, you're right that it is a challenge to figure out how to implement the context-sensitive pop up Bookstack already has without resorting to some kind of text selection. If a Bookstack page incorporates headings in its content, you could possibly add an invisible button (made visible only to screen readers) that opens the pop up at that heading or section of content, but that wouldn't work if the page doesn't contain headings.

[c0shea]

In case anyone else has been annoyed by not having the page permalink easily accessible without the pop-up menu, I wrote a script that can be added to the Custom HTML Head Content under Settings > Customization. By putting the customization here instead of modifying the view code directly, it won't be lost or have to be re-applied on future upgrades.

This adds a "Copy page permalink" link under the Details section on the page that, when clicked, will copy the permalink to your clipboard.

Just replace URLTOYOURBOOKSTACKINSTANCE with the fully qualified URL to your BookStack instance.

<script type="text/javascript">
    window.addEventListener('load', function() {
        document.body.addEventListener('click', function(event) {
            if (event.target.id === 'page-permalink') {
                let pageId = document.querySelectorAll('div[option\\:page-display\\:page-id]')[0]?.getAttribute('option:page-display:page-id');

                if (!!pageId && !!navigator.clipboard) {
                    navigator.clipboard.writeText('https://URLTOYOURBOOKSTACKINSTANCE/link/' + pageId);
                }

                return false;
            }
        });

        document.querySelectorAll('div[class=entity-meta]')[0]?.insertAdjacentHTML('beforeend', `
            <a href="#" class="entity-meta-item" id="page-permalink">
                <svg class="svg-icon" data-icon="link" role="presentation" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
                    <path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z"></path>
                </svg>
                Copy page permalink
            </a>
        `);
    });
</script>

[ssddanbrown]

Hi @neosonic2,
I've been dedicating some time to this today, with a bunch of changes added within commit 88785aa. These changes include the following:

• The "pointer" (Popup which includes the permalink in addition to other controls) will now be moved within the DOM upon show, so it sits before the section it's displaying for. This allows you to access it via focusing on the previous element on the page.
• At the bottom of the page content, is a "Section select mode" button, which is visually hidden but accessible to screen readers/keyboards. Selecting this button will update each major block within the page content to be focusable, and focus will be placed on the first such block (Page title). You can then cycle through the other main content blocks via focusing in adjacent items on the page. Pressing enter on any of these blocks will show the pointer and place focus within it.
• You can now close/exit the pointer via the "Escape" key.
• The pointer has been updated so that the pointer, and all buttons & inputs within, are now properly labelled for accessible use.

I've tested these changes using Firefox and the built-in screen-reader included with Fedora/Gnome, which I believe is Orca.
From my testing everything is now quite accessible and correctly descriptive, therefore I'm going to close this off and these changes will be part of the next feature release (Currently targeting end of June).
That said, I respect that I'm not a everyday screen reader user so it's possible there could be awkwardness or issues with my initial implementation here, but I'm totally happy to iterate and improve upon these changes after getting actual user feedback so please don't hesitate to raise further issues if required once you have a chance to use the implemented changes.