Taking MkDocs to the next level #3622
Replies: 23 comments 47 replies
-
As I stated in another discussion, my knowledge in Python is limited, so I wouldn't be one to provide code contributions or even suggestions (i.e. code improvements) in that area. I would be open for joining, tho, I hope there are some clear guidelines regarding team organization and specific procedures on stuff like PR reviews, discussing new features/changes, etc. to ensure things are handled in a structured way. |
Beta Was this translation helpful? Give feedback.
-
I’d like to follow along as well. |
Beta Was this translation helpful? Give feedback.
-
I'm really psyched to see this happening and will do my very best to contribute as much of my time as I can! Putting maintenance of MkDocs on more shoulders is definitely overdue and the logical next step, given the history and popularity of the project. Let us plugin and extension authors work together and take this project to the moon 🚀 |
Beta Was this translation helpful? Give feedback.
-
Thanks for tagging me on this! I'd love to be more involved, though I'm not sure how much time I'll be able to dedicate to MkDocs. I'll try to help out where I can. |
Beta Was this translation helpful? Give feedback.
-
I would love to contribute! I can certainly share ideas, time and my talent, but I may not be the best software engineer. I can hack on a mkdocs plugin pretty well, but I am primarily a Product Manager by profession with specialties and expertise in Developer Experience. I would love to contribute those talents if I can. One specific area I would love to contribute to is the creation of a mkdocs-powered OpenAPI specification renderer. I would like to explore either partnering with a community like Redoc, or Stoplight (or similar) to develop an API Reference module, or develop a native one ourselves. I have other thoughts and ideas to share, but will save them for a more appropriate forum. Thank you for the invite! |
Beta Was this translation helpful? Give feedback.
-
Yes, I'm okay with being included. |
Beta Was this translation helpful? Give feedback.
-
Very in! Haven't had much of a need to touch my MkDocs code in a while, but I'm planning on using it/working on plugins in the near-ish future. Not sure how much direct code I can contribute due to time constraints, but I'd love to be included in discussions! Sick idea btw! |
Beta Was this translation helpful? Give feedback.
-
I think it's a good idea, and I feel honored that you asked me to join. If I can help in some way, I will be happy to. One of the things I have dreamt about for some time, is some self-hosted web app, which could be a container for static websites, especially MkDoc. Something which had its proper log-in procedure, where we could easily define user groups, with access rights for read and write, and provide a navigation to access the various sites (read/write would translate, in terms of git, as git pull and git push). Basically it would be the "wiki shell", a container for a number of documentation projects. That would look like a very poor man's Git Pages or ReadTheDocs... Writing such a piece of software would be little beyond my ability and resources right now, but just in case somebody liked the idea... |
Beta Was this translation helpful? Give feedback.
-
Interesting! I've got some ideas in my backpocket to help make general documentation projects a bit more interactive and it's also way past due for me to update the calmcode course (it's 4+ years old ... possibly the 2nd course that I ever made ... and it should be updated to feature the plugins/customisability more). Can't say for sure how much time I'll have though, but keen to be in this particular loop. |
Beta Was this translation helpful? Give feedback.
-
All this sounds exciting, and I am happy to see that this group is full of creative spirit. @koaning mentioned his calmcode course (kudos), which was evidently produced using a Jupyter notebook. I am currently using Jupyter Lab in a consulting project since it is very adequate to document and illustrate my research work on the go. As a big fan of Don Knuth's Literate Programming, I just cut the traditional distinction between "research" and "report", and started to tangle and weave as I go). That also has to do with the philosophy behind Mkdocs-Macros... Once one has tasted the exciting properties of dynamic Markdown, it's hard to go back to "normal life". Now the Markdown cells in Jupyter seem too plain to me, and I wish they also integrated a Jinja2 environment that exploits the variables of the notebook. It seems so easy to implement it (that is, for the initiate who understand how Jupyter works, which I am not)... and so elegant. Actually, somebody thought of implementing a similar functionality to Mkdocs + Macros but frankly it just looks like an usine à gaz compared to the simple elegance of Markdown extensions used in Mkdocs, the beauty of Material, and the powerful elegance of Jinja2... We even know how to do Mermaid diagrams, with or without a dedicated plugin. What does it have to do with Mkdocs? I am not so sure. Just some lateral thinking... |
Beta Was this translation helpful? Give feedback.
-
So far I haven't contributed to the main MkDocs repo, but I'm developing my own set of plugins MkDocs Publisher. I have some ideas to improve documentation related to plugin development and maybe some small things into the code (already implemented in one of my plugin, but kind of fell that this should be part of the core). It could be grat to be a part of such a great community even deeper. |
Beta Was this translation helpful? Give feedback.
-
Thanks @pawamoy for thinking in me. I love the idea of fostering collaboration this way and I'm honored to be included <3. Right now I'm trying to invest the least time in the maintenance of my MkDocs plugin and thus in the MkDocs ecosystem, but I'd love to be in the loop. One thing that is being in my mind is to support orgmode as well as markdown. I've switched this year to the other side of plaintext and I'm loving it. I was thinking on using Thank you so much for the initiative :) |
Beta Was this translation helpful? Give feedback.
-
Thanks for tagging me! I can help, though it will depend on the level of time commitment you're looking for. |
Beta Was this translation helpful? Give feedback.
-
Good Idea, count me in. Mkdocs and the plugin system around it is really cool. And compared to other solutions in the field, I am somewhat able to follow how it works under the hood, which is important to me. Until now, I've never felt the urge to add code or suggestions to mkdocs itself (just some small discussion on issues), because I always thought the big boys (the maintainers) know it better. It's sad seeing a dedicated person like oprypin go away, but let's keep this as a reminder to always try to be excellent to each other. |
Beta Was this translation helpful? Give feedback.
-
Thanks @pawamoy for this proposal, the initiative is excellent ! As I currently struggle to maintain all of my packages in parallel with contributions to others' and running professional/family life, I prefer not to commit to core design discussions/maintenance actively, but will be happy to discuss topics directly related with how |
Beta Was this translation helpful? Give feedback.
-
Thanks for the invite! Happy to collaborate. I have not been spending much time on my mkdocs plugins due to family & work. But I am excited to think along. I also like the idea of having an I think there are opportunities for making plugin development even easier. One idea I have to is enable adding standard options like I also had on my backlog for a long time the wish to build a standardized git 'meta plugin' that processes markdown pages just once and as fast as possible (multithreading, parallel, etc). Then plugins authors that use that information easily and efficiently. I even started an implementation on https://github.com/timvink/mkdocs-git-info-plugin but have never properly dedicated the time required. |
Beta Was this translation helpful? Give feedback.
-
I'd be down to assist if everything is public. |
Beta Was this translation helpful? Give feedback.
-
Thanks for inviting me, I am honored! |
Beta Was this translation helpful? Give feedback.
-
Thanks for inviting me! I changed jobs and my new employer uses Docusaurus, so I no longer have time to collaborate on MkDocs. But I wish this project all the best, it deserves all the success in the world 🚀 |
Beta Was this translation helpful? Give feedback.
-
Thanks for inviting me! I'm excited to join this group and help improve the MkDocs community. I've learned so much about managing open-source projects from both you and @squidfunk. I'm currently preparing a talk for COSCUP(Conference for Open Source Coders, Users & Promoters) in Taiwan (fingers crossed it gets selected, haha) on how MkDocs can enhance documentation for open-source projects. I hope this presentation will help more people see how awesome MkDocs is. |
Beta Was this translation helpful? Give feedback.
-
Hey @pawamoy, many thanks for inviting me, and apologies for the delayed response. I can try and commit some time to maintenance 🙂 I'm in agreement with others above that it's likely better for the project to adopt an open development model which plans in public, and encourages developers within the community to collaborate on reviews. A smaller, more privileged group of core developers that emerges from such a group could be granted the ability to merge/reject PRs as appropriate. I struggle to see a benefit to non-public project coordination and planning, and that exclusivity introduces a barrier to possible contributors. |
Beta Was this translation helpful? Give feedback.
-
Hi there, I'm getting late here and I feel like I've missed a train or two! I'm interested even though my investment in the Mkdocs ecosystem is on my spare time and I'd rather not promise you a huge commitment. On a broader level, I'm a firm believer in community dynamics in open source projects, and I've often had the impression that the open source aspect of Mkdocs remained very (too?) closely linked to one or a few people at most, without any real community dynamic. I have a similar feeling about the Material for Mkdocs project, but it's likely more understandable since it's the @squidfunk's project and there's a business model with a company behind it (even an individual one). Maybe it's not yet time to bring out the heavy artillery of open source project management (PSC, etc.), but why start with a private discussion space and not a public one? |
Beta Was this translation helpful? Give feedback.
-
Hello again everyone, @tomchristie and I moved forward and decided to transfer all discussions that were created in the private space mentioned here into the public, main repository 🙂 Use the category filters on the left (Maintenance, Meta, etc.) to find some of them. The possible next step is to create a team for all users and authors who expressed interest here. This team would give them a bit more privileges (triaging, approving PRs? to be defined yet with core maintainers). |
Beta Was this translation helpful? Give feedback.
-
Update, April 22
All the discussions created in the private space mentioned below were moved into the public discussions of the MkDocs main repository 🙂
Hello everyone,
I'm Timothée aka @pawamoy, you might have met me here and there in the MkDocs ecosystem. I maintain mkdocstrings and had some very nice interactions with some of you :)
I've been participating and collaborating on MkDocs as well for some time now, helping answering questions from users, and sending a few pull requests.
After some discussions with @tomchristie (original MkDocs author) and @squidfunk (Material for MkDocs author), we've come to the realization that it's high time we expanded our team, especially in light of recent events. Given the prolonged periods where MkDocs has relied heavily on individual contributors, we believe it's crucial to onboard more people to ensure the sustainability and growth of the project.
In line with this goal, @tomchristie has created a private space (a repository in the MkDocs GitHub organization with the Discussions feature activated) where we can foster better communication and collaboration among community members, by inviting authors of MkDocs themes and plugins, and authors of Markdown extensions. This space will serve as a platform for suggesting ideas for MkDocs and discussing how we can improve MkDocs to better serve plugin authors like ourselves. It will also be a place to discuss about project organization (like issue management, policies, onboarding new maintainers, etc.), while ensuring progress and maintaining focus on our objectives.
We believe that your involvement would greatly benefit the MkDocs community, and we'd be thrilled to have you on board. If you're interested in joining us, please let us know! This could be a way for us to get more maintainers on the team too.
I will tag some authors and contributors here directly, in alphabetic order:
@Andre601 @athackst @bczsalba @blueswen @byrnereese @chrieke @daizutabi @EddyLuten @facelessuser @fralau @greenape @Guts @JakubAndrysek @koaning @LukeCarrier @lyz-code @mondeja @ofek @ojacques @six-two @smarie @timmeinerzhagen @timvink @unverbuggt @waylan @wilhelmer
Beta Was this translation helpful? Give feedback.
All reactions