Docs website formatting is broken about docs HOT 24 CLOSED

What you're looking for can be found here, https://github.com/cucumber/docs/blob/main/content/docs/cucumber/api.md#tags

not sure why it doesn't show up in the docs.

from docs.

Based on what I saw in #813 I'm guessing that we went from Hugo < 0.55 to Hugo >= 0.85. And there appear to have been some changes to how templates work. E.g:

https://gohugo.io/content-management/shortcodes/#shortcodes-with-markdown

This way too much work right now.

@mattwynne it also appears that we now have a cucumber-hugo and cucumber-smartbear template. Perhaps you can pull in some of the folks who did the original migration.

from docs.

They got renamed to "Conditional Hooks" in 325d223. The subject matter didn't really change. Are you missing anything specific?

from docs.

I just access the URL before last dec-2022. The commit you have given is last 2019. The detail I'm looking for is the info about how the tags can use with multiple scenarios.

As you see in the pic when I try clicking tags hyperlink, it navigates to nothing as I far I can remember it, the cucumber reference have docu for tags usage.

Update: I check the repo docs.

https://github.com/cucumber/docs/blob/main/content/docs/gherkin/reference.md

In feature,

This is what I'm trying to find the tags info, but trying to access this I guess, it has been removed?

Maybe I'm not remembering it right but I'm sure that's where I got my notes about tagging.

from docs.

Looks like the conditional has gone unbalanced just after the Around. But I'm really not seeing which one.

https://github.com/cucumber/docs/blob/main/content/docs/cucumber/api.md#around

@olleolleolle I think this is partially due to the surprise Hugo upgrade #813.

from docs.

Seeing how the "WebDriver" is no longer inline with the rest of the sentence it looks like everything gets turned into paragrapths. I'm not sure which syntax we use for the short codes but if it's go template like we might have to use {{- and -}} to trim whitespace and maybe put it all on one line.

https://github.com/cucumber/docs/blob/main/themes/cucumber-hugo/layouts/shortcodes/text.html

https://pkg.go.dev/text/template

from docs.

What you're looking for can be found here, https://github.com/cucumber/docs/blob/main/content/docs/cucumber/api.md#tags

not sure why it doesn't show up in the docs.

Thanks I see it now.

from docs.

Had a quick look and see a few more issues with the page. Nothing after the header "Install plugin" is shown (in any language tab), and the page above that header doesn't look great either, for example: 1) some code blocks are not properly formatted, 2) there are new lines where there shouldn't be. I'll try to have a look later as to why, and how to fix it.

from docs.

If you're trying to reproduce this locally, be sure to use hugo v0.85.0. This is the current version of Huge used by Netlify.

from docs.

https://gohugo.io/content-management/shortcodes/

from docs.

1. {{text}} blocks should be rendered inline (not start on new line)

• For some reason {{text}} blocks are not / no longer rendered inline, while they should (block is defined as <div>, text is defined as <span>.

2. Code blocks immediately at the start of a {{text}} or {{block}} section should be formatted as code

• For some reason code blocks (starting with three backticks) that are right at the beginning of a {{text}} or {{block}} without any preceding text are not / no longer rendered properly. (i.e. the text with backticks is shown, instead of a code block)

To see if this has been resolved, revert one of my workarounds in #827 where I add text or a newline between the start of the {{block}} and the start of the code block.

For example:

{{% block "kotlin" %}}

```kotlin

to

{{% block "kotlin" %}}
```kotlin

from docs.

Reported by Benjamin in Slack: "Hello, I noticed a bug in the Cucumber documentation (not with the text itself but with the functionality.
On the Java reporting page https://cucumber.io/docs/cucumber/reporting/?lang=java, the sections “Custom formatters” and “Third-party plugins” are not visible. These are only there on the “JS” page https://cucumber.io/docs/cucumber/reporting/?lang=javascript
Since my own “Third party plugin” is a Java/Maven plugin, this is of personal interest "

from docs.

3. Links at end of sentence not shown correctly.
For some reason markdown links are not rendered correctly when followed by a period at the end of a sentence. Or when followed directly by a closing shortcode. (adding a workaround to remove the period / add new line before closing shortcode; and sometimes that workaround doesn't work either)

For example, at the end of these pages:
https://cucumber.io/docs/cucumber/api/?lang=javascript
For more information on how to configure options, have a look at the cucumber-js docs on GitHub

https://cucumber.io/docs/cucumber/api/?lang=ruby
You can also define common command-line options in a cucumber.yml file.

Also, in the middle of this page: https://cucumber.io/docs/cucumber/api/?lang=java

from docs.

4. Markdown formatting should be rendered correctly, eg ** should be bold
Using ** to make text bold is sometimes rendered correctly, and sometimes not. I've not been able to figure out why.

from docs.

Managed to partially fix the issue(s), mostly with workarounds. Looks like front end stuff from here, which is outside of my area of interest. Maybe @mattwynne and/or @aslakhellesoy can have a look?

from docs.

This might be a better option:

https://docs.netlify.com/integrations/frameworks/hugo/#hugo-version

from docs.

ugh, OK leave it with me

from docs.

5. Lists are not rendered correctly
I've "fixed" this in #827 by adding a newline before the start of the list. Revert this workaround to see if it has been fixed.

For example:

{{% block "java,kotlin" %}}

* `message`
* `progress`
* `pretty`
* `rerun`
* `junit`
* `testng`

to

{{% block "java,kotlin" %}}
* `message`
* `progress`
* `pretty`
* `rerun`
* `junit`
* `testng`

Also see
https://cucumber.io/docs/guides/10-minute-tutorial/?lang=javascript
List after "Please be aware that this tutorial assumes that you have a:" is not rendered correctly on all pages. It looks fine on Java page, but on JS page:

from docs.

6. Inline "code" formatting is not always rendered correctly.

https://cucumber.io/docs/cucumber/api/?lang=java
For example:
"Step hooks are invoked before and after a step. The hooks have 'invoke around' semantics, meaning that if a BeforeStep hook is executed the AfterStep hooks will also be executed regardless of the result of the step. If a step did not pass, the following step and its hooks will be skipped."

"BeforeStep" and "AfterStep" are between backticks and should be rendered as red text, like "Before"and "After are later on the page:

"Hooks can be conditionally selected for execution based on the tags of the scenario. To run a particular hook only for certain scenarios, you can associate a Before or After hook with a tag expression."

from docs.

@mlvandijk thanks for flagging these items and providing examples. I'll get the SmartBear Web Devs to take look as soon as possible.

from docs.

In light of the recent developments around SmartBear and Cucumber I don't expect this will be fixed soon.

from docs.

@mpkorstanje we will continue to support the Cucumber Open community. Some resources should be freeing up shortly to get these items resolved.

from docs.

@mlvandijk and @mpkorstanje - I've made a change in the build configuration for the docs that seems to have resolved many of the issues mentioned above. The Dockerfile has Hugo configured at version 0.40 where as the version in production was 0.85.0.

Please confirm that this adjustment fixed the above issues.

from docs.

Looks good! Cheers!

from docs.