lightbend / antora-ui-lightbend-theme Goto Github PK

We are currently adding the language selection on top of the main page.

If would nice if we add it to a place that is always visible.

• Menu sidebar
• "On This Page" sidebar
• top bar where we have the breadcrumbs (probably not great)

Paradox has it on the menu sidebar, just above the search. I find it a better place then the "On This Page" sidebar, but we can experiment eventually.

This is a feature request. If it's possible to highlight in bold, italic, color, or whatever in the ToC which section is being viewed, or as a compromise, which one was last clicked, that would be helpful for reorienting where you are.

I find when I'm navigating the draft Platform docs, I want to use the ToC to select the next the items (since the new docs are not all one page, like FDP and Pipelines docs), which means I have to read the ToC and find where I was...

@rasummer, I happened to view source and noticed that the canonical url is not generating in the meta data any more. I tried with both the regular layout and the default_layout: default-lightbend-cloudstate layout. This isn't the case with the antora-ui-lightbend-cloud-theme. Looking at the published cloudflow.io docs, I see the url metatag.

It would be nice to have a "clipboard" icon on source code blocks so that readers wouldn't have to select the code manually to copy it. Maybe something like this: https://clipboardjs.com/

As discussed here:
https://github.com/akka/akka-platform-guide/pull/322#discussion_r508310150

Ideally we could solve that using styling.

It can be a challenge when including different fragments by toggling the same tag.

For instance, this:

// tag::SendOrderProjection[]
import shopping.order.proto.ShoppingOrderService;
import shopping.order.proto.ShoppingOrderServiceClient;
import akka.grpc.GrpcClientSettings;
// end::SendOrderProjection[]

public class Main extends AbstractBehavior<Void> {

    public Main(ActorContext<Void> context) {
        // tag::SendOrderProjection[]
        ShoppingOrderService orderService = orderServiceClient(system);
        SendOrderProjection.init(system, orderService);
        // end::SendOrderProjection[]
    }

    // can be overridden in tests
    // tag::SendOrderProjection[]
    protected ShoppingOrderService orderServiceClient(ActorSystem<?> system) {
        GrpcClientSettings orderServiceClientSettings =
                GrpcClientSettings
                        .connectToServiceAt(
                                system.settings().config().getString("shopping-order-service.host"),
                                system.settings().config().getInt("shopping-order-service.port"),
                                system)
                .withTls(false);

        return ShoppingOrderServiceClient.create(orderServiceClientSettings, system);
    }
    // end::SendOrderProjection[]
}

will show as:

import shopping.order.proto.ShoppingOrderService;
import shopping.order.proto.ShoppingOrderServiceClient;
import akka.grpc.GrpcClientSettings;
        ShoppingOrderService orderService = orderServiceClient(system);
        SendOrderProjection.init(system, orderService);
    protected ShoppingOrderService orderServiceClient(ActorSystem<?> system) {
        GrpcClientSettings orderServiceClientSettings =
                GrpcClientSettings
                        .connectToServiceAt(
                                system.settings().config().getString("shopping-order-service.host"),
                                system.settings().config().getInt("shopping-order-service.port"),
                                system)
                .withTls(false);

        return ShoppingOrderServiceClient.create(orderServiceClientSettings, system);
    }

while we probably want it to be:

import shopping.order.proto.ShoppingOrderService;
import shopping.order.proto.ShoppingOrderServiceClient;
import akka.grpc.GrpcClientSettings;

ShoppingOrderService orderService = orderServiceClient(system);
SendOrderProjection.init(system, orderService);

protected ShoppingOrderService orderServiceClient(ActorSystem<?> system) {
    GrpcClientSettings orderServiceClientSettings =
        GrpcClientSettings
            .connectToServiceAt(
                system.settings().config().getString("shopping-order-service.host"),
                system.settings().config().getInt("shopping-order-service.port"),
                system)
            .withTls(false);

	return ShoppingOrderServiceClient.create(orderServiceClientSettings, system);
}

Most probably we can't solve this with styling though.

We will need to have different tags: tag::SendOrderProjection-part1[], tag::SendOrderProjection-part2[], tag::SendOrderProjection-part3[], etc.

The asciidoc syntax for bold is one or two asterisks: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#formatted-text

Antora is converting these to in the HTML, but apparently our css doesn't have a definition for that? The doc convention is to use bold to indicate when we are describing part of the UI, such as, select Save from the File menu.

one question,

how to Activate the pagination?

thank

best regards Ludwig

For example, look at the Maven/sbt tabs on this page: https://lightbend.github.io/openshift-deployment-guide/Tutorials/deploying-lagom/configuring-akka-cluster.html#_cluster_bootstrap

The Akka Platform guide is defaulting to Java.

When we switch to Scala and navigate to another page, the language jumps back to Java.

We should find a way to preserve the language selection. Cookie?

According to the example shown on this blog: https://mrhaki.blogspot.com/2017/10/awesome-asciidoctor-grouping-floating.html

The following markup should scale the three images and line them up across the page: [.float-group]

image::grafanaAkka.png[Akka metrics,width="25%",float="left"]
image::clusterPage1.png[Main dashboard,width="40%",float="left"]
image::grafanaHomeExpanded.png[Grafana dashboard,width="25%",float="left"]

I tried this in the index page for: https://github.com/lightbend/lightbend-console-docs/tree/master/docs/modules/ROOT/pages and couldn't make it work. I suspect we need some css styling to make it happen? The desired output is similar to the images on: https://developer.lightbend.com/docs/console/current/index.html

Many of our projects trigger a redeployment of Tech Hub when a branch is pushed to GitHub (also including when pull requests are merged).

@rasummer and @rstento if you're happy to have the theme trigger automatic deployments, I can configure it.

(Or anyone with admin access to the repo can configure it following the instructions in the private Tech Hub repo.)

I'll wait for your responses before I change anything.

I'd like the ability to be able to inject custom scripts into the template, without having to fork the template. I'm not sure how/whether Antora supports this (if it does at all).

My use case is in Cloudstate, when we used Paradox we had some JavaScript that looked up the current released version of the CLI from our CLI downloads server, and automatically updates references to it in our pages so that our pages always pointed to the latest version of the CLI, rather than us having to manually update them. I'd like to be able to include this script in the Lightbend UI theme for the Cloudstate docs - in the footer so that it doesn't slow initial render of the page down.

Code examples that use long callout text can be hard to read.

For example: https://lightbend.github.io/openshift-deployment-guide/Tutorials/deploying-lagom/configuring-shopping-cart.html#_view_the_configuration_files

Notes:

• The number label is vertically aligned with the middle, rather than the top, of the associated description. This makes it hard to see where each number starts.
• The line spacing is the same between items as it is within each item, making it hard to see where one item ends and the next begins.

A few weeks ago when I added the supergroup for Cloudstate for web-cli tabs, it worked. Today it doesn't and I can't figure out why. I've attached the source from a page where I've defined and used them. The tabs appear OK, but there is no selector at the top. When I inspect, the supergroup switch css element is there, but empty:

@rasummer, if you could help me figure this out, it would be great. I also realized that it would be better if the group were named supergroup-browser-cli, with tabs named "Browser" and "CLI" because it seems more user friendly to refer to the app in the browser than as a "web UI".

Source from the prev page:
= Creating a Cloudstate project
:toc:
:toc-title: ON THIS PAGE
:toclevels: 2
:page-supergroup-web-cli: Interface
include::ROOT:partial$include.adoc[]

A project is a collection of Lightbend Cloudstate services and related items that comprise your application. Cloudstate projects support team collaboration: Multiple people can be members of a single project, and each person can be a member of many projects.

Cloudstate project names must conform to the following:

• Up to 253 characters
• Can include lowercase letters
• Can include numbers
• Can include hyphen “-” (not underscore”)
• Cannot include spaces

To create a project:

[.tabset]
Web::
+
. Sign into your Cloudstate account.

• The My Projects page opens.
  . Click new project.
  . Enter a Project name following the constraints described above.
  . Enter a user-friendly name in the Project description field.
  . Click submit.

Your project should appear in the My projects list. A Cloudstate admin will need to activate the project before you can use it.
CLI::
+
. Log into your Cloudstate account:
+

csctl auth login

The web UI launches in a browser.
+
. Enter your credentials.
+
An authorization page displays.
+
. Click Authorize
+
. Create a project by substituting your project name and placing a descriptive name in quotes:
+

csctl project new “friendly name”

At this point, your project is empty, and you are the only person who is a member of it.

== Project status

Along with the project name and description, you will see a project status. This status may begin as PENDING until the project has been approved by a Lightbend Cloudstate administrator, at which point it will show as ACTIVE, and you can continue using the project to deploy services.

If your project does not move to ACTIVE status in a short time, please email us at mailto:[email protected][[email protected]] and let us know the project name.

NOTE: You can also use the command line, csctl project list, to see a list of all projects you have access to (or have created). See xref:manage-project-adoc[Managing projects] for more information.

== What's next

Next, you will use the command line to xref:auth-kubectl.adoc[authenticate kubectl to your project].

Some hyphenations look weird. Example:

I think this is hyphens: auto in the css.

Can we turn it off, and also consider making the width of the content area increase with the window size?

This is supported in Paradox. It will be cool to have the same here.

It's possible to select the language by passing a querystring, eg: ?/lang=scala.

This is specially useful when crosslinking documentation, but also when sending a link to a customer in order to make them land on the right page and language.