Skip to main content

Linking within LivingDoc

Comments

17 comments

  • Andreas Willich

    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

    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

    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

    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 

    2
  • wim.swinkels

    I'm facing similar issues with links to feature files running the CLI, in html the link stays empty.

    <a href>Link Feature</a>

    Is there any way to fix this?

    The url to one of a page also contains a ID in stead of the feature name.

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

    @Richard Cutts do you have a solution to the problem?

    0
  • Aaron Steinmetz

    Just starting using livingdoc this week, the linking feature appears completely broken to me. All 'links' simply reference livingdoc.html.... always goes to the root. 

    Did anyone manage to fix this, it's a 3 month old problem is appears. any luck wim.swinkels ? Richard Cutts ? Not sure if Andreas Willich this is an acknowledged bug? 

    I am calling the CLI from my \bin directory: 

    livingdoc test-assembly SpecFlowProjForDeploymentMonitor.dll -t TestExecution.json

    but when i open the livingdoc.html in chrome, and hover over the link i made, it only points to 

    file:///Z:/CodeGithub/ARRB/Hawkeye/misc-utils/PostBuildServerDeploymentMonitor/SpecFlowProjForDeploymentMonitor/bin/Debug/net48/LivingDoc.html

    Rather than any of the Feature.feature files that i have in my project. ?

    Thanks.

    0
  • Richard Cutts

    Sorry to say that no, I was never able to successfully create any internal links to other features.

    For me they all link to the root as described above.

    1
  • Aaron Steinmetz

    I wonder if the issue exists on their Azure Devops implementation as well. We don't use it so not much use to me either way i suppose. I'd be interested to see the SpecFlow team's Feature File on being able to link documents. Shouldn't they have a BDD feature file on this, and unit tests to ensure it works? A little bit of irony. ;-)

    I tease though, it's a very interesting platform and i'll try and make it work regardless.

    0
  • Fabio Cocchi

    Same here.

    A little bit of context:

    • generating LivingDoc with feature-folder method
    • my features files are in Project\Features\Category\file1.feature and file2.feature
    • path does not contains any space

    I've done the following attempt:

    1. in the Project folder
    2. executed
      livingdoc feature-folder .\
      with the following link
      Project\Features\Category\file2.feature
    3. executed
      livingdoc feature-folder .\Feature
      with the following link
      Features\Category\file2.feature
    4. executed
      livingdoc feature-folder .\Feature
      with the following link
      Project\Features\Category\file2.feature
    5. moved to Features folder
    6. executed
      livingdoc feature-folder .\
      with the following link
      Features\Category\file2.feature
    7. executed
      livingdoc feature-folder .\Category
      with the following link
      Category\file2.feature
    8. executed
      livingdoc feature-folder .\Category
      with the following link
      Features\Category\file2.feature

    None of them works. Every link is bringing me to the homepage.

    1
  • Denis Willems

    Same here, both from Azure Devops than with CLI.
    From Azure Devops, I don't have to now from with directory is executed the script.

    Is there a working example somewhere ? None of the replies seems to show it's even possible...

    Thank you...

    0
  • Richard Cutts

    Yeah, I'm almost certain this is a bug.

    And, despite it being relatively inconsequential, the fact that it exists; that an example of it is reproduced in their own example; that the issue hasn't really been acknowledged; and the inability for me to do anything about it (i.e. closed source) has led my company to abandon the product.

    We've had to go with other tools we either trust to be supported or we know we can maintain ourselves.

    So a great little tool and an excellent demonstration of possibilities. But not suitable for real world use imo. To be expected of a free closed source tool, so no great suprise.

    0
  • Aaron Steinmetz

    Richard Cutts can I ask which 'other tools' you looked at please? Feel free to DM me if you like.

    Thanks

    0
  • Denis Willems

    Also interested with returns about other tools of course, even if I can't understand this functionality is not possible (anymore?) with livingdoc. 

    The most famous open source tool seems to be picklesdoc (https://github.com/picklesdoc/pickles), but it's far less complete...

    Futhermore, I was not able to use "internal" images with livingdoc, as documented here: https://docs.specflow.org/projects/specflow-livingdoc/en/latest/Generating/Markdown-and-Embedding-Images.html

     

     

    0
  • Aaron Steinmetz

    Denis Willems I recall playing with the images and had mixed success with it. I think this whole product is a great idea and i hope it will work, but it does need some TLC in a few other areas than they seem to be focusing. 

    0
  • Richard Cutts

    It really depends on what you want from it.

    If you are looking for functional equivalence then I imagine you will need to continue to use the Specflow library and either persevere with livingdoc or, as mentioned above, integrate with Pickles or https://github.com/Augurk/Augurk/ (or roll your own. You have the bdd and test results in a structured files. Read them, generate some output.)

    These doc generation tools don't have feature parity with livingdoc but they are open source so if you need to expand, improve, or fix them, you can do so.

    CucumberStudio is a saas product in the same space but again, no feature parity.

    So if this feature set is exactly what you want with no compromise and now development then you have to swallow the fact its a free, under supported tool.

    We ended up working in a different way. Using Azure DevOps and some plugins for our specs and docs.

    0
  • Morawitz Markus

    I also experience the same problems: internal links and local images are not functioning.

    I am very new using SpecFlow but at the first glance it seems to be really impressive and I would like to use it on our projects including the generation of living documentation which I find an awesome concept.

    I wonder if there is any possiblity to create something like a bug report and get information about its progess and future plans.

    0
  • Morawitz Markus

    I just found a kind of workaround to get internal links to features working.

    Looking at the generated living doc html document each feature is presented by a url containing a unique hash code of the feture name and path.

    For example: LivingDoc.html#/document/Standalone/feature/6d60af7e35a2465b1ab05cda960898ca

    Which in my case is a feature titled “Context Diagram” in the folder “Context”.

    Using an html tag instead of the markdown in another feature like this:

    <a href="#/document/Standalone/feature/6d60af7e35a2465b1ab05cda960898ca">Context Diagram</a>

    I get a working link from a second feature to my context diagram feature.

    As I assume my feature titles and folder structure pretty stable I think this workaround will be a good work around. Although I would prefer the markdown syntax as described in the user documentation.

    0

Please sign in to leave a comment.

Powered by Zendesk