Bug 265276 - Books: FAQ and other single-page books: Single HTML: 404
Summary: Books: FAQ and other single-page books: Single HTML: 404
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Books & Articles (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Some People
Assignee: Sergio Carlavilla Delgado
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2022-07-17 20:45 UTC by Graham Perrin
Modified: 2023-01-28 13:58 UTC (History)
3 users (show)

See Also:


Attachments
Use single page layout for one page books (3.42 KB, patch)
2023-01-27 20:09 UTC, Ciarán Ainsworth
no flags Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Graham Perrin freebsd_committer freebsd_triage 2022-07-17 20:45:21 UTC
1. <https://docs.freebsd.org/en/books/faq/>

2. under Resources, click Single HTML

Expected: 

3. if the initial view was truly split, a switch from split to single

Actual result: 

3. <https://docs.freebsd.org/en/books/faq/book/> 404 not found
Comment 1 Fernando Apesteguía freebsd_committer freebsd_triage 2022-10-09 16:03:30 UTC
^Triage: reporter is committer, assign accordingly.
Comment 2 Graham Perrin freebsd_committer freebsd_triage 2022-12-04 10:55:26 UTC
Help, please! 

I have _NO_ idea how to patch things such as this.
Comment 3 Ciarán Ainsworth 2023-01-26 13:25:23 UTC
The reason this happens is that the theme generates a single HTML link that is hardcoded to the `book.adoc` file in a given directory. This file includes all chapters to present everything in a single page. However, for pages like the FAQ and the dev-model, this is unnecessary. These are already single page documents.

You have a few ways to handle this:

1. Create a `book.adoc` file that contains all the content from the index page (don't do this).
2. Update the theme and add a frontmatter parameter which allows the editor to hide the single page link when it's not necesssary.
3. Find some way to inform Hugo when there's no book file and have it simply route the user back to the main page when they click the link.

Of these, 2 is by far the easiest to implement as we can just add a parameter like `show_single_page: false` to the frontmatter of single page docs and the theme won't show the link, thereby avoiding the confusion.

If this sounds like an agreeable solution, let me know and I'll put a patch in.
Comment 4 Ciarán Ainsworth 2023-01-27 20:09:18 UTC
Created attachment 239746 [details]
Use single page layout for one page books

Looking at this again, I can see this issue affects the following books:

1. The Design and Implementation of the 4.4BSD Operating System: https://docs.freebsd.org/en/books/design-44bsd/
2. A project model for the FreeBSD Project: https://docs.freebsd.org/en/books/dev-model/
3. Frequently Asked Questions for FreeBSD 12.X and 13.X: https://docs.freebsd.org/en/books/faq/

This patch takes the following steps to address the issue:

1. Updates the "single.html" template used for one page books to remove the link to the single HTML page (this is redundant when you're already in the single HTML view and just refreshes the page)
2. Applies the "single.html" template on single-page books using the "layout: single" frontmatter parameter.
Comment 5 commit-hook freebsd_committer freebsd_triage 2023-01-28 08:55:34 UTC
A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=34aaac36f56c4b56a168d9f392f5bc2a25998a63

commit 34aaac36f56c4b56a168d9f392f5bc2a25998a63
Author:     Ciarán Ainsworth <ciaranainsworth@posteo.net>
AuthorDate: 2023-01-28 08:53:27 +0000
Commit:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
CommitDate: 2023-01-28 08:53:27 +0000

    Fix single page problem in FAQ, dev-model and design-44bsd

    PR:             265276
    Reported by:    grahamperrin@

 documentation/content/en/books/design-44bsd/_index.adoc | 1 +
 documentation/content/en/books/dev-model/_index.adoc    | 1 +
 documentation/content/en/books/faq/_index.adoc          | 1 +
 documentation/themes/beastie/layouts/books/single.html  | 4 ----
 4 files changed, 3 insertions(+), 4 deletions(-)
Comment 6 Sergio Carlavilla Delgado freebsd_committer freebsd_triage 2023-01-28 08:56:21 UTC
Fixed! Thanks for the patch!
Comment 7 Graham Perrin freebsd_committer freebsd_triage 2023-01-28 13:58:43 UTC
Thanks :-)