[jira] [Commented] (SOLR-15556) Ref Guide Redesign Phase 3: Replace Jekyll

["Cassandra Targett (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/SOLR-15556?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17394253#comment-17394253 ] 

Cassandra Targett commented on SOLR-15556:
------------------------------------------

There's a very early version of what the Guide might look like with Antora up on my people pages: https://people.apache.org/~ctargett/experiments/antora/solr/9_0_0/index.html (username: apache password: solr)

The UI elements are only very partially updated to be similar to what we have today, but basic look & feel is similar enough, and with some nice stuff Antora's default UI brings to the table. Thought folks might enjoy an early preview.

There's a lot still broken so huge grain-of-salt with this:

- Links in the left nav work, but lots of links inline in content do not (they show up as red). There are over 1200 inter-page links that need to be reviewed for syntax and path corrections after moving files around.
- Images and code examples should be working.
- Footer isn't done, some branding is still WIP, DRAFT watermark and title lookup box are missing, etc.
- I haven't figured out yet how to pull variables like ZK version, jetty version, etc., out of versions.lock so only a few of these are hard-coded and the rest are not working right.
- pages still have page-children, etc., which isn't actually used in this model (but you won't notice that in the UI)
- and probably lots of other stuff I'm forgetting right now or haven't found yet

This is buried in my notes a bit, but if we move to manually maintaining our nav instead of auto-generating it, we have a lot more control and would be able to get rid of ~20 pages I think that are almost entirely navigational. This would also clean up some of the duplication you can see in the breadcrumbs/left-nav (Home -> Deployment Guide -> Deployment Guide, for example). So FYI that looks odd too.

> Ref Guide Redesign Phase 3: Replace Jekyll
> ------------------------------------------
>
>                 Key: SOLR-15556
>                 URL: https://issues.apache.org/jira/browse/SOLR-15556
>             Project: Solr
>          Issue Type: Improvement
>      Security Level: Public(Default Security Level. Issues are Public) 
>          Components: documentation
>            Reporter: Cassandra Targett
>            Assignee: Cassandra Targett
>            Priority: Major
>
> The final step of my grand vision for redesigning the Ref Guide is to look at replacing Jekyll with a different static site generator.
> The primary reason why is because Jekyll is designed for blog posts, not for sites with hundreds of static pages like ours. Back in 2017 when I chose it, it was relatively straightforward to implement, a lot of information was available in Jekyll docs and the internet in general to customize it, and it was one of the few that supported Asciidoc format. 
> However now there are a lot more options, including some which are specifically designed for large multi-version documentation sites like the Ref Guide.
> Included with this will be reorganizing the on-disk organization of the ref guide files themselves.



--
This message was sent by Atlassian Jira
(v8.3.4#803005)

---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org