Linking within LivingDoc

Richard Cutts

• August 17, 2022 16:25

I am struggling to understand how the linking within the LivingDoc should work.
Hoping someone can point out my gap in understanding.

I have looked at the docs page here: https://docs.specflow.org/projects/specflow-livingdoc/en/latest/Viewing/internal-linking.html

I couldn't tell if the syntax is supposed to include chevrons or not as the documentation text doesn't have them, but the code sample does:

[text](link/to/feature.feature)

or

[text](<link/to/feature.feature>)

So, I created a VS2022 project from the SpecFlow Project template and generated the LivingDoc for the sample Calculator feature using the CLI. The Calculator.feature file included looks like this:

Feature: Calculator
![Calculator](https://specflow.org/wp-content/uploads/2020/09/calculator.png)
Simple calculator for adding **two** numbers

Link to a feature: [Calculator](SpecFlowProject1/Features/Calculator.feature)
***Further read***: **[Learn more about how to generate Living Documentation](https://docs.specflow.org/projects/specflow-livingdoc/en/latest/LivingDocGenerator/Generating-Documentation.html)**

@mytag
Scenario: Add two numbers
    Given the first number is 50
    And the second number is 70
    When the two numbers are added
    Then the result should be 120

 

The LivingDoc that the template project generated shows a link for "Calculator" where you would expect, but clicking the link just reloads the page. I opened the LivingDoc html file before realising it's not a file for reading :D

If I right click the link and inspect the element, the html shown is:

<p>Link to a feature: <a href="">Calculator</a>

0

• 

  Andreas Willich

  • August 18, 2022 13:57

  You are using MarkDown in the descriptions. And you need the '<>' if you have spaces within the path.

  If you don't have spaces, you can leave the <> brackets out.

  Yeah, the example in the project is not the best, but the only thing that is possible. We wanted to show how you link to different feature files but didn't want to add a second feature file to the template only to show this feature. So we link to itself.

  Does this help you understand it better?

  0
• 

  Richard Cutts

  • August 18, 2022 14:12
  • Edited

  Thanks Andreas,
  Understood re the link syntax, thanks.
  
  The problem that I am having is that in my own project, I have 2 feature files.
  
  

  • MyProject/Features/First Feature.feature
  • MyProject/Features/Second Feature.feature

  And one has a link to the other, like so:

  Feature: First Feature
  
  - This feature relates to [Second Feature](<MyProject/Features/Second Feature.feature>)
  
  ...

  But in the html output:

  <a href>Second Feature</a>

  So when it's clicked it just reloads the whole document and doesn't navigate to the feature.

  
  I would have expected perhaps something like

  <a href="#/document/Standalone/feature/{id}">Second Feature</a>

  
  It was after observing this behavior I checked the calculator example for guidance.

  Is it most likely some bone headed typo on my part? If the path can't be resolved it is just omitted entirely from the output?
  
  

  0
• 

  Andreas Willich

  • August 18, 2022 14:47

  That linking works is dependend on the directory you are executing the cli command from.

  What is your CLI command and in which folder are you executing it?

  0
• 

  Richard Cutts

  • August 19, 2022 09:23

  Specification/Features/*.feature

  Running the CLI from the Specification folder (the root of the VS project)

  livingdoc test-assembly '.\bin\Debug\net6.0\Specification.dll' --title 'Functional Specification' -t .\bin\Debug\net6.0\TestExecution.json -o 'Functional Specification.html'

   

  Also, the BookShop example in github is displaying the same behavior I'm seeing.

  https://specflowoss.github.io/LivingDoc-Demo/BookShop.html#/document/Standalone/feature/0dfd8d6cc2f7c14535bd568205ed9741 

  0

Please sign in to leave a comment.