>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #2522024. --> Reported by: [jhodgdon](https://www.drupal.org/user/155601) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>On <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/infrastructure/-/work_items/2503371" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/infrastructure/-/work_items/2503371</a></span>, the infra team set up a temporary site for the <a href="https://www.drupal.org/project/user_guide">User Guide project</a>. We are currently using this site to develop and display the project as we go; see:<br> <del><br> THESE ARE THE OLD URLs<br> <a href="https://userguide-drupal.redesign.devdrupal.org/d8guide/en/index.html">https://userguide-drupal.redesign.devdrupal.org/d8guide/en/index.html</a> (in-progress guide)<br> <a href="https://userguide-drupal.redesign.devdrupal.org/guidelines/index.html">https://userguide-drupal.redesign.devdrupal.org/guidelines/index.html</a> (guidelines and instructions)<br> </del><br> <a href="https://userguide_new-drupal.dev.devdrupal.org/d8guide/en/index.html">https://userguide_new-drupal.dev.devdrupal.org/d8guide/en/index.html</a> (in-progress guide)<br> <a href="https://userguide_new-drupal.dev.devdrupal.org/guidelines/instructions.html">https://userguide_new-drupal.dev.devdrupal.org/guidelines/instructions.html</a> (guidelines and instructions)</p> <p>This is OK for the moment <del>, but our process for getting the project's source and HTML output files up there is manual right now: jhodgdon builds the output and uses SFTP to transfer it to the site; she also logs in and does a git pull to update the source directory. This needs to be replaced with a Jenkins job or similar.</del> [This part has been taken care of]</p> <p>Also, we need a more permanent home for the site.</p> <h3>Specifications / Features</h3> <p>Desired features of the more permanent home for the User Guide (each feature is given a code name for easy reference below):</p> <ul> <li>[git] The definitive source for the Guide is a Git repository. Due to the ability to have branching, multiple translations, patches, etc., we do not want to lose that.</li> <li>[display] We would like to display the guide in HTML form, which can be built from the source and ideally updated when the source is updated.</li> <li>[integration] Ideally, it should look like other Drupal documentation, and be integrated with other Drupal documentation (which is in nodes on Drupal.org).</li> <li>[ebook] People should also be able to download PDF and other e-book versions of the guide, which are also built from the source and should ideally be automatically built and updated when the source is updated.</li> <li>[multilingual] The guide will be translated, so we would like to display all the language versions (HTML and e-book downloads).</li> <li>[edit] Allow contributors to edit the guide on-line and download revised text source files for the pages, and to see project information (file an issue link, link to the project, etc.).</li> <li>[versions] The Guide will need to be branched for different versions of Drupal. For 8.x.y versions, we can probably live with just displaying the most current branch. But when 9.x is in development and/or close to release or released, there will definitely be a significant time when we'll need to have both the 8.x and 9.x versions available to view/download, because presumably 8.x and 9.x versions of Drupal will be in widespread use.</li> <li>[additional] We may eventually have more books (like Volume 2: Advanced Views or something); would be good to display them too. We already actually have 2 books -- one is the "contributor guide" for people working on the Guide, and the other is the Guide itself.</li> <li>[discover] We'll need to direct people to this Guide, and ideally if they search drupal.org these pages would come up in the search results</li> </ul> <p>Note on [edit]: The editorial workflow for the guide uses issues in the <a href="https://www.drupal.org/project/user_guide">User guide project</a>. Basically, if someone wants to propose a change they would need to file an issue in that project, and the maintainers would then examine the changes to the text source files and commit them. The current online editor we have on the dev site allows people to preview the AsciiDoc output as they write it, and then download the revised text file that they can attach to an issue. Many of our contributors are using the online editor now, and as we move forward with updates needed for new versions of Drupal being released, and with translating the guide into new languages, this need will continue. The online editor also has support for [multilingual], as it lets you see the English source while you're translating.</p> <p>Features we don't need on this site:</p> <ul> <li>Comments</li> <li>Generally people logging into the site, except possibly one or two admins to edit some settings or maybe the home page; we could probably even get around that by putting the settings in a Feature and generating the home page from another AsciiDoc project?</li> <li>The pages of this site are not directly related to Drupal.org pages, although we may put in manual links on docs pages to the manual, or in the manual to docs pages.</li> </ul> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <h4>Option 1 for implementing these features: AsciiDoc Display module in Drupal site</h4> <p>On the current dev site, features [display], [multilingual], [edit], and [additional] are being taken care of by using the <a href="https://www.drupal.org/project/asciidoc_display">AsciiDoc Display in Drupal</a> module. (Well, to be clear, the multilingual feature works in that module, but we don't currently have any multilingual source so the block that enables it is not being displayed.)</p> <p>Feature [ebook] has not been implemented, but the User Guide project has scripts that generate PDF, ePub, and Mobi output (they may need some work to make better output, but they do work). We'd probably need a small module that would list the e-book versions in a block or page.</p> <p>Feature [discover] - no idea how to make this work with the Solr multisite search, but it might be possible to do.</p> <h4>Option 2 for implementing these features: static HTML site</h4> <p>On some of the comments on this issue, it was suggested that for the HTML output, we could use a static HTML site generated directly from the AsciiDoc source. However, it's not clear how this would support features [multilingual], [edit], [additional], or [ebook]. It seems like we'd need some kind of PHP scripting for that or sidebar blocks or something, and if we're going to do that, it seems like we should use Drupal.</p> <h4>Note on having a separate site vs. on Drupal.org itself</h4> <p>Assuming we're displaying this in a Drupal site, we'd also need to decide whether to put it on <a href="http://www.drupal.org">www.drupal.org</a> itself or in a docs.drupal.org or similar subsite.</p> <p>Considerations:<br> - Multilingual - <a href="http://www.drupal.org">www.drupal.org</a> currently isn't, but may be soon due to groups migration<br> - Fragmentation - may be better to have it on <a href="http://www.drupal.org">www.drupal.org</a> for unity<br> - Getting lost - may be better to have it on its own site so that it stands out more and the navigation/blocks can be specific to that site</p> <h4>Option 3 - Import AsciiDoc HTML output into Drupal.org nodes</h4> <p><strong>This is the option we are planning to implement</strong></p> <p>Build a way to import the HTML output of the AsciiDoc source into Drupal nodes in the appropriate language(s). This would be a modification (or sub-module) of the AsciiDoc Display module, which would provide a Drush command to import a "book" into Drupal nodes, and another one to update existing nodes (so it would need to have a database table to keep track of the correspondence). We would plan to do the import of a given language when the guide is deemed to be "stable" in that language, and then update it (by running a Jenkins job that would be available but not run automatically) when deemed to be a good idea.</p> <p>Features to be added later:<br> - Ability to do on-line editing (using AsciiDoc Display module, connected to the nodes but reading the source as it does now, should be easy enough since we will have the table with the correspondences)<br> - Ability to download PDF and ePub ebooks (Jenkins can build and copy to a standard location, and links can be put into a block that is displayed on these pages)</p> <p>This satisfies most/all of the desired specifications/features.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <p>- Decide on the eventual home<br> - Build the site<br> - <del>Set up Jenkins scripts [jhodgdon can provide information; will need to install 4 Apt/Yum packages but the scripts themselves are straightforward]</del> Done!<br> - Modify the existing Jenkins scripts to point to the new site.</p> <h3 id="summary-ui-changes">User interface changes</h3> <p>Permanent home for the User Guide, with auto-generated HTML and e-book output.</p> > Related issue: [Issue #2503371](https://www.drupal.org/node/2503371)