#Content Collections/ Markdown Navigation

1 messages · Page 1 of 1 (latest)

bitter python
#

Hi,

I'm building a Starlight site that I'm importing content from an old Azure DevOps wiki into, and I'm struggling to get the Markdown navigation working.

Given the following structure:

| index.md
  -| Folder
     | index.md
     | Another-File.md
    -| Nested-Folder
        | index.md

How do I create navigation link from /Folder/Nested-Folder/index.md back to say /Folder/Another-File.md and then back again?

Current they're either relative to the markdown file, or based on the root.

I'm doing a lot of pre-processing on this files, so I can play with the link prior to it coming into Astro/ SL.. but it appears as though the there is no-build/ re-writing with Startlight/ Astro itself - so authors would need to know what the relative url would be when authoring content, rather than to the path of the MD file... is that correct?

rare gyro
#

Assuming that your structure is all under /src/docs/content/, I would say that the links /Folder/Another-File and /Folder/Nested-Folder should work respectfully for navigation.

I have to admit that I didn't fully get what you are asking in the last paragraph. Can you maybe share the use case / why you are doing the pre-processing or maybe just some code (if the project is public)?

bitter python
#

Sorry, yeah - it's a odd one to try and explain.

Under the src/docs/content folder would be say the following file:

/Cloud-Engineering/Azure-DevOps/Pipeline-Principals/index.md

That has a bunch of links like so:

- [Template Conventions](Template-Conventions.md)
- [Converting an Existing Project (from Classic to YAML or YAML to YAML Templates)](Converting-Existing-Projects.md)
  - [How to Make Sure Your Pipeline Works](Make-Sure-Your-Pipeline-Works.md)
  - [After Converting a Pipeline](After-Converting-Pipeline.md)
    - [Environments](Environments.md)
    - [Repositories](Repositories.md)
    - [Service Connections](Service-Connections.md)
- [Application Pipelines](/Cloud-Engineering/Azure-DevOps/Pipeline-Principles/Application-Pipelines)
- [Infrastructure Pipelines](/Cloud-Engineering/Azure-DevOps/Pipeline-Principles/Infrastructure-Pipelines)

Some of those files are referenced as being relative to the current file.

However, some are relative to the root of the src/docs/content folder.

My question, more succinctly, is: What should those links look like in the Starlight/ Astro world to they correctly navigate to the actual content.

rare gyro
#

The last two links in the example should be how you do it in Starlight, I don't know if it's possible to link to files relatively from the current file, but maybe I just don't know...

- [Application Pipelines](/Cloud-Engineering/Azure-DevOps/Pipeline-Principles/Application-Pipelines)
- [Infrastructure Pipelines](/Cloud-Engineering/Azure-DevOps/Pipeline-Principles/Infrastructure-Pipelines)
bitter python
#

In the example above, the rooted links are automatically directed to the .md file that represents the link (/Cloud-Engineering/Azure-DevOps/Pipeline-Principles/Infrastructure-Pipelines => /Cloud-Engineering/Azure-DevOps/Pipeline-Principles/Infrastructure-Pipelines.md)

In the Astro/ SL world... should these be links to the .md files - relative or absolute - and the build process takes care of generating the correct url, or should content authors link to the URL?

I've not seen any concrete information on the subject.

rare gyro
#

You just need to link to the relative path, but without the URL, Astro handles the rest.

Because in Astro, your Markdown files automatically get exposed as routes, which do not include the file extension. Therefore, you can link to these paths. 🎉

Does this answer the question or do you need further info?

bitter python
#

Trying to figure out what I need to do to the original files to get them linking correctly.

And it sounds like they all links to other md files have to be relative file references, and Astro converts that to a url as it renders the html?

rare gyro
#

Yes, Astro uses very basic navigation which you can use in your Markdown files as well, and it gets converted to the right URL when you built (or in dev mode).

Like in your case, I think adapting the /Cloud-Engineering/Azure-DevOps/Pipeline-Principals/index.md file like that should work:

- [Template Conventions](/Cloud-Engineering/Azure-DevOps/Template-Conventions)
- [Converting an Existing Project (from Classic to YAML or YAML to YAML Templates)](/Cloud-Engineering/Azure-DevOps/Converting-Existing-Projects)
  - [How to Make Sure Your Pipeline Works](/Cloud-Engineering/Azure-DevOps/Make-Sure-Your-Pipeline-Works)
  - [After Converting a Pipeline](/Cloud-Engineering/Azure-DevOps/After-Converting-Pipeline)
    - [Environments](/Cloud-Engineering/Azure-DevOps/Environments)
    - [Repositories](/Cloud-Engineering/Azure-DevOps/Repositories)
    - [Service Connections](/Cloud-Engineering/Azure-DevOps/Service-Connections)
- [Application Pipelines](/Cloud-Engineering/Azure-DevOps/Pipeline-Principles/Application-Pipelines)
- [Infrastructure Pipelines](/Cloud-Engineering/Azure-DevOps/Pipeline-Principles/Infrastructure-Pipelines)

So what I changes is all links that had .md in the end:

  1. Prepend /Cloud-Engineering/Azure-DevOps/ (I assume that all these files live under this folder, if not, you need to adjust the folder accordingly)
  2. Remove the .md extension

Have you tried this yet? If so, is this what you were expecting as an answer or is still something unclear?

So to answer this question:

In the Astro/ SL world... should these be links to the .md files

No. Just link to the files without the extension (.md).

bitter python
#

Thanks - yeah, I had to do some work to figure out relative/ correct paths. But that was it.

I'll need to find a way to get the content authors using urls instead of md files... or keep it as a pre-build/ preview/ dev stage as they're unlikely to get it right.

Turns out the ADO Wiki is very forgiving.

Thanks for the massive assist! 💪