[
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: [email protected]
For additional commands, e-mail: [email protected]
