Document how to build locally and stage a change for PR

[perpil]

Description

I was trying to modify the code to add a stroke width to the text on social cards. Although there is documentation on how to modify a theme, there isn't documentation on how to modify the code and submit a PR. I kind of figured it out by looking at the package.json. Can you document the global packages you need to install, which targets to run for local modifications and how to submit a PR without so many deltas? Are you supposed to remove the material/ directory before submitting a PR?

Related links

• Reporting a docs issue
• how to modify a theme

Proposed change

No response

Before submitting

• [X] I have read and followed the documentation issue guidelines.
• [X] I have attached the links to the affected sections of the documentation

[alexvoss]

Hi, thanks for reaching out. The process for setting up a development environment is documented under Getting Started/Customization/Theme development . From what you are saying about what you were trying to do this does not seem like a bad place? I have recently done some work on this and as a new collaborator have an interest to get this right, so please let me know if there is anything specific that should be changed.

Re the pull request question - I do think this could do with documenting. Apart from the question about the materials/ folder, I am not sure how much there will be to say, though. Then, we might be surprised once we talk down that path. Some tests run automatically using GitHub actions, so you will get feedback if you broke anything we have a test for.

[perpil]

I think the page we linked to covers most of it, but there are a few things missing. Namely, I found I needed to run pip install -e mkdocs-material after building to have the code that I modified take effect. This may be because I have insiders. When I get time, I'll follow the guide and take notes on any additional steps I needed to take.

[HonkingGoose]

Setting up the correct development environment setup is a hard part of contributing to any project. Have you thought about automating the setting up your environment step?

In the Renovate repository we have a .devcontainer setup [^1], so any contributor can open a GitHub Codespace and get coding quickly. The .devcontainer has everything the contributor needs:

• ESLint
• Prettier
• Jest
• Test scripts
• And so on

So in short:

• Fully describe what's needed in for local development
• Create a GitHub Codespaces configuration for remote development
• You may also want to look into creating a Gitpod config, they give away free compute hours too

[^1]: Renovate .devcontainer directory

[squidfunk]

A .devcontainer was already added in https://github.com/squidfunk/mkdocs-material/commit/a9d8eab935c95394e4ec93f7352510570e2b8d2e. Frankly, I'm not a user of code spaces, so I'm not abkle to maintain this. If this can be improved, feel free to open a PR so we can discuss. That being said, @alexvoss is actively working on improving the instructions how to get up and running locally.

However, most contributions are docs-only, or very small bug fixes, so I'm not sure making it simpler to set up the environment is the fire we should be putting out first. There are other things that need our (and specifically my) focus right now. As always, it's a matter of priorities. You know how it is to maintain a popular Open Source project.

[alexvoss]

I am also not a user of codespaces - at least not yet. Given that they make 60 hours of usage free, I might just do the odd job in the cloud instead of on my laptop if it works well. I will have a look at it and post some thoughts but today and tomorrow I am tied up with other projects.

My experience is that with a Mac or Linux box setting things up is not very difficult. My experiences with Windows were decidedly more mixed as soon as non-Python dependencies got involved. In my environment, I usually cut and paste the instructions from the environment setup section and it works fine. I have been developing with vim and tmux but I can see the advantages of a modern IDE, especially having a usable interface to a debugger.

On thing I did notice is that VSCode seems to be running the build, so no need to run npm start in a separate window?

One problem I have had was that my breakpoints were not hit because I set them in the files in src but had to set them in material instead, then remember to actually edit the files in src. At least for me as a beginner in this realm, these issues were more of a hurdle than the environment setup as such. Codespaces would not fix this, I guess.

[squidfunk]

@alexvoss could you follow up on this? I think since you did some PRs lately, you're likely have a pretty good yet-outsider experience that'll likely result in a better guide than if I would cobble something together, since I'm probably blind having internalized all of the processes that are necessary to get things going 😅

[alexvoss]

Can do but am traveling today, so will be tomorrow US East time.

[squidfunk]

No hurries, just wanted to know whether there are any impediments I can help with ☺️

[alexvoss]

Sorry it has taken me so long to make progress on this. There is a draft PR now with a description of the usual process for a PR from the point of view of the repositories involved. I illustrated this with some Mermaid sequence diagrams. It would be good if you (all) could have a look at let me have some feedback.

Following the description of the process there are then some notes on specific steps. All of this is very much work in progress and I would love to hear if this is going in the right direction from the point of view or people likely to create PRs. I know some more writing will be needed but perhaps you see some glaring omissions or things that are wrong or confusing? I hope to get this out of draft this over the next few days and request a formal review.

[alexvoss]

Just to say that I have added more content to the draft page describing the PR process. Constructive comments very welcome. There are a few questions in there in some places where I was not entirely sure how to proceed. Hope to put this baby to bed soon, so I can turn my attention to all the other things on my guilt-pile...

[squidfunk]

And we're live! Thanks again to @alexvoss for this tremendous effort. This, surely, looks like a lot of work, and provides significant value to the project! Love it!