online Markdown editors #10586
online Markdown editors #10586
Conversation
✅ Deploy Preview for astro-docs-2 ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Lunaria Status Overview🌕 This pull request will trigger status changes. Learn moreBy default, every PR changing files present in the Lunaria configuration's You can change this by adding one of the keywords present in the Tracked Files
Warnings reference
|
Co-authored-by: Kian <[email protected]> Co-authored-by: HiDeoo <[email protected]> Co-authored-by: Thomas Bonnet <[email protected]> Co-authored-by: Reuben Tier <[email protected]>
Co-authored-by: Kian <[email protected]> Co-authored-by: HiDeoo <[email protected]> Co-authored-by: Thomas Bonnet <[email protected]>
thomasbnt
dismissed
their stale review
The word 'synchronise' has been modified.
Co-authored-by: Armand Philippot <[email protected]>
sarah11918
added
add new content
There was a problem hiding this comment.
Left one small note on the infrastructure, but it looks solid to me — nice work!
Regarding the general idea, I’m not entirely convinced this content belongs in Astro’s documentation. Might be veering into “this could be a great blog post!” territory? It’s all great content, really well put together, but I don’t know if the Astro docs website is the right venue.
These tools can definitely be helpful to people, but the key documentation content here seems to usually be the “Edit an existing file” type sections which are often 7–8 steps describing specific UI flows in these products. That means they’ll be wrong every time one of these products changes their UI slightly, which we won’t know about. So I’m not totally convinced that the maintenance burden will be low. Plus the guidance mostly seems to not be specific to Astro, so we get little benefit from documenting this ourselves vs linking to each product’s documentation.
For a comparison, I guess I’d ask if we’d write similar guides for GitPod/StackBlitz/Code Sandbox/IDX/Codespaces/etc. or VS Code/WebStorm/Zed/Sublime Text/etc., which all seem to fall into a similar zone to me of “Tools you might use to build Astro projects”, but which we wouldn’t have lots of specific guidance for. Maybe content more like our “Editor setup” page would make sense? A page with links to useful tools to provide the general conceptual “You can use online Markdown editors!” idea.
I’d also raise a concern for the impact on site search. Working with Markdown is often a key part of Astro sites and this PR introduces a bunch of new pages with “Markdown” in their title, which will compete for priority with our higher value Astro-specific Markdown usage documentation. I find it a bit hard to predict exactly how that would shake out and we can’t easily test what Algolia would do, but wanted to flag that as a concern.
Anyway, like I said, this is great content put together with care, so don’t want to be too down on it, but raising my concerns!
| @@ -48,6 +48,12 @@ export const integrationSchema = baseSchema.extend({ | |||
| githubIntegrationURL: z.string().url(), | |||
| }); | |||
|
|
|||
| export const markdownSchema = baseSchema.extend({ | |||
| type: z.literal('markdown'), | |||
| stub: z.boolean().default(false), | |||
There was a problem hiding this comment.
I don’t think this is used anywhere? So may be worth omitting? We can always add it back later if we decide stubs are needed.
There was a problem hiding this comment.
Just checking that we don't need this for defining type: markdown to classify this as a markdown editor for the editor nav!
There was a problem hiding this comment.
The stub property? No, only the type property is needed!
My suggestion might have been ambiguous sorry, here’s concretely what I was suggesting:
| stub: z.boolean().default(false), |
Just didn’t want to add an explicit suggestion without confirming first that stub wasn’t in use elsewhere.
|
Thanks, Chris! All super helpful points! The impact on searches for "Markdown" is indeed a real concern no one had yet brought up! And considering external searches, admittedly these don't bring the same SEO benefit the CMS guides do (even if the CMS guides similarly end up polluting our search results at times.)
It's a good point, and also content I have thought about whether is appropriate (some of which I have written on my own blog personally). Something closer to Editor Content is absolutely an option for content like this! What prompted me to think this might be a little different is that we do have CMS guides, which are similarly about managing your content externally. One differences is that these third-party services are simple enough that working with Astro is no different than working with any other service. Some CMSs are like that, others aren't and the instructions for Astro specifically might not be that different from using in any other situation. But we do know that CMSs are a hot topic in the Discord and can be the thing that allow some people to choose Astro. (They wouldn't consider a project without a CMS to go with it.) While it's true they also wouldn't use Astro without a code editor, we don't get people coming in to the Discord asking "Which code editors work with Astro?" nearly the same way. So the parallels are there re: this isn't content for us to cover, but it also happens to be more related to content that's arguably "on the bubble" that we have decided to cover. Again, not arguing for necessarily, just explaining why I wanted to explore this content for docs.
Yes, though I will point out that these have been strategically chosen as editors that really don't change very much. Some have not had updates in 6 or 7 years. 😄 They really are bare-bones, just functional tools. I'm not in a rush to decide/merge, but did want to make sure the infra was solid in case we do decide to move forward with this! |
|
Yeah, like you say, I think on balance the explicit documentation for how to integrate a CMS with Astro is quite different from Markdown editors because those guides do quite often have a fair bit of Astro project set-up/code to show. Whereas instructions for these editors mostly boil down to:
This is a good point and also to me a difference compared to Markdown editors — whether a GitHub Markdown file is editable online is not the differentiator for one tool or another on the whole. Any site generator etc. that has in-repo Markdown is compatible with any of these tools, not just Astro, so this wouldn’t be part of a decision to use/not use Astro.
These ones may have been, but there are lots of online editors out there. Would we be in a good position to tell someone making a PR that theirs shouldn’t be here too? 😅 |
|
Alright, thanks everyone for your help and feedback! I'm going to close this one for now as we focus on other things and consider whether there's a good place for this content elsewhere! |
Description (required)
Adds a new third-party guide category for online Markdown editors that sync to GitHub as a cross-platform/OS, low-friction way to manage content in an Astro repo (fix typos, update text, add a new blog post, etc.)
These guides are presented as minimal/lightweight alternatives to a CMS for more basic content editing needs. Many of these do not even require an account (only permission for the website to link to GitHub).
Larger "philosophical" discussions took place (below) as to whether these are necessary, helpful etc. and we may ultimately decide these are not for docs. However, I do believe that this category is appropriately scoped and defined in such a way as to keep the maintenance burden low while providing discoverability for an entire category of helpful web dev tools that isn't well known.
Notably (as discussed on Talking and Doc'ing):
Admittedly, there is little Astro-specific content (other than connecting to an Astro repository hosted on GitHub) but some of our CMS content is also not very Astro specific because it works the same whether Astro or not. these services happen to be simple enough that there is little Astro-specific guidance to give, but also an entire category of tools that is not well known and people might not easily discover on their own. This is more about having content to direct people who ask about options for "non-technical" contributors but for whom a CMS might be more than they need. Like a CMS, this is a tool some might be interested in using, but one where the type of project/repository doesn't happen to matter.
includes "awesome" link to Markdown editors, including local/desktop ones for various operating systems (but desktop apps are out of scope for these guides). The overview page mentions that desktop apps, or any text editor, can be used to create Markdown, and these can be directly added to a repository. So, it makes people aware of similar local options to give them an idea they could explore, but does not attempt to document how any one particular application works as out of scope. (Too much maintenance burden, not every application is available for every platform/OS...) At least browser editors work in any browser, on any device.. and also don't tend to update frequently.