Will need to wait for https://github.com/coder/coder.com/pull/84 before merging this.

I've replaced all mentions of up next with the new syntax/style in the coder oss docs.

tested the new tag syntax the other two doc repos. they work on coder v1 and coder OSS docs. found an issue on code-server, roman will fix it as soon as he can however there are no up next sections to replace in code-server as of right now.

contributors can use this syntax to link docs via these tags (just make sure to use paths from the manifest file):

Will update as soon as i can verify the new tag works on code-server.

This'll look a bit weird for anyone viewing the docs on GitHub, the heading will be visible but <doc> doesn't show up. Do we want to maintain compatibility or guide people towards not using the docs in the repo?

@mafredri I was looking on <children> tag while implementing this
https://github.com/coder/docs/blob/main/admin/index.md?plain=1#L20

This'll look a bit weird for anyone viewing the docs on GitHub, the heading will be visible but <doc> doesn't show up. Do we want to maintain compatibility or guide people towards not using the docs in the repo?

Hmm. I didn't foresee this issue when planning out this task. Originally I was trying to reduce the markup so the contributors had less to write.

I think we should definitely push users to our site's docs for marketing/website goals wherever we can on outside platforms

I might have a solution, I'll try submitting a proposal tonight.

What do you guys think about this workaround?

Allow contributors to use markdown like they normaly would so github gets the markdown as intended:

then in the markdown parser on our site, we use regex to select ## Up next or ## Next steps and convert any markdown links in that ## section into those cards. We'll have to do some testing to make sure performance isn't affected.

this way contributors have less to write when linking the next steps but we get those fancy cards.

ofc the other option is letting the up next cards be HTML. not pretty but the simplest solution here.

let me know what you think.

Also, what are your thoughts on adding a cta to the bottom of all the docs on github to get people into our site's docs? If we use the markdown parser solution we can strip it out when the docs get rendered on our site, this way the cta will only appear on github docs. i have a few text variants in figma.

figma for ref: https://www.figma.com/file/LYL5VURCZ5lMgtUDiuEvER/Coder-V2-(In-Process)?node-id=563%3A2044

I think that solution is good.

What do you mean by the docs site thing? Do you mean that every markdown doc should have that in the footer?

What do you mean by the docs site thing? Do you mean that every markdown doc should have that in the footer?

Yeah, i think it's gonna be good to try to get that traffic back to our docs through a cta/link on every docs .md file. We can have a global link for each of the 3 docs.

It will not only direct users from GitHub back to our domain but also the people who use docs in their IDEs. the more returning users to our site the better I think.

the only downside is it's a bit repetitive for this use (and to maintain) but it should be worth it for all the extra traffic we can get back. another option is to use it sparingly on the top-performing doc pages (based on GA).

I'll assign roman to do the regex implementation of the cards. and I can analyze GA what are the top visiting pages on each of the docs to add that CTA, if you think we should go the sparingly route vs all pages.

I think something like that would be good for the README doc, but it would be too repetitive and easy to forget for the rest.

This Pull Request is becoming stale. In order to minimize WIP, prevent merge conflicts and keep the tracker readable, I'm going close to this PR in 3 days if there isn't more activity.

Just waiting on @BrunoQuaresma to approve https://github.com/coder/coder.com/pull/84 before merging this in.

Just waiting on @BrunoQuaresma to approve coder/coder.com#84 before merging this in.

It is approved!

Hmm.. @antonkor I'm not seeing these blocks format correctly. I'm running yarn dev on coder.com's master.

@ammario PR to convert links to markup is not merged yet
https://github.com/coder/coder.com/pull/101

@rzubov anything I can do to help move this forward?

@rzubov anything I can do to help move this forward?

I missed this issue in my inbox til now. Lets see how Ammar responds.

@jsjoeio Is there anything I need todo to resolve the "release / linux-windows (push)" and "coder / test/go (windows-2022) (push)" checks? Or is that stuff we can overlook?

@jsjoeio Is there anything I need todo to resolve the "release / linux-windows (push)" and "coder / test/go (windows-2022) (push)" checks? Or is that stuff we can overlook?

Try resolving your conflicts and rebasing on top of main, pushing and seeing if that fixes it 🤞🏼 Hoping just a flake.

@jsjoeio Conflict are resolved