Publishing custom changes

[A3Bagged]

Hello, im not sure if this is documented somewhere but i've tried google, in here, youtube with different search options.

(heavily modified css)

I've followed the Theme development guide and i've changed the website a lot using extra.css and custom overrides for homepage. When i do npm run build it completely wipes everything back to default (luckily i keep backups) The info there isn't super helpfulll & i git cloned the default material repo with a bunch of other files which im not sure i need.

So right now i've just pushed everything to the repo but the custom css (of the materials/ folder with every override etc in it) everything is in there. I did use the non-insiders version for this because i can't use the insiders repo and push it to the repository for everyone to be seen and grabbed. How do i prevent this?

Currrently the website looks like this.
(its not 100% done still has some minor issues but it's online for the people that will be writing the md files to view the layout)

It's a documenting page for a project of someone that im doing the web for, github is still fairly new to me and i dont think i can upload the material/ folder to a private repo since all paths inside the directory are local. How do i prevent insiders things from being public?

---

Side question: Why does material use a font size of 125% on the html? Makes no sense and having to reset the html for the homepage made everything tiny. I've had to compremise and add calc in my css to scale my rems down from 125% to 100% using:
--fs-display-m: calc(clamp(2.5rem, 1.5767vw + 2.1305rem, 3.313rem) * 0.8); the trick here is calc(input * 0.8);

Why isn't 1rem 16px by default?

Thanks in advance

[kamilkrzyskow]

Hello @A3Bagged,
I feel like you have some misconception on what the Theme development section is 🤔

The section should be referred to only when somebody:

• wants to make changes which are impossible with extra.css nor custom overrides in their documentation project
• plans to have a lot of projects using the changes, and maintaining multiple extra.css files and synchronizing overrides between projects would be too much of a hassle
• wants to make a fundamental change and make a PR to this (or Insiders) repository to share the improvements / fix with others after the PR has been merged

From the looks of it you want to maintain one documentation project, so theme development isn't relevant in your case, and an extra.css file with overrides should suffice.
The npm run build command, builds the theme from the src directory into the material directory. The SCSS is compiled into CSS files etc. and all files are basically recreated removing all of the changes you've made in the material directory. That's why there is the warning:

Never make any changes in the material directory, as the contents of this directory are automatically generated from the src directory and will be overwritten when the theme is built.

i git cloned the default material repo with a bunch of other files which im not sure i need.

You don't need any of the files from this repository inside your documentation project. Consider MkDocs and the Material theme as an application, which someone has to install separately, and execute with the custom changes you've made in your own documentation project directory.

Instead of the theme development, your docs page should be the Publishing guide:

• https://squidfunk.github.io/mkdocs-material/publishing-your-site/

Examples:

• GMC (repo)
  • custom_dir: overrides with block overrides and some other stuff including the extra.css
  • installation for the build process happens in local workflow action
• Nype (repo) - uses the inheriting mkdocs-nype theme
  • custom_dir: overrides with home.html and some other stuff
  • extra.css in the docs/assets directory
  • installation for the build process is handled with reusable action from the theme

I did use the non-insiders version for this because i can't use the insiders repo and push it to the repository for everyone to be seen and grabbed. How do i prevent this?

The same logic applies to the Insiders variant, which should be put in a private fork, and then you would give your docs maintainers access to the private fork, so that they can install it locally, and the same for your github actions which would install it during build. TBH I don't know if it would be easier to setup a GitHub organization or just give access to people to your private fork. Also remember to have a hard fork copy of the Insiders version as a plain GitHub fork would be removed once you lose access to the main Insiders repository.

You can look at my auto-update GitHub actions which uses an access token to retrieve the Insiders data:

• Auto updating the insiders version with an action #7562 (comment)
• https://$GITHUB_ACTOR:[email protected]/<MY_USERNAME>/mkdocs-material-insiders.git

I also believe that requirements.txt for Python projects should support environmental variable substitution in similar fashion.

Side question: Why does material use a font size of 125% on the html?

I'm not a webdev, so idk. Supposedly there is some math shenanigans to make it easier for subsequent changes / accessibility.

mkdocs-material/src/templates/assets/stylesheets/main/components/_base.scss

Lines 31 to 37 in 1f78e37

	// Hack: normally, we would set the base `font-size` to `62.5%`, so we can
	// base all calculations on `10px`, but Chromium and Chrome define a minimal
	// `font-size` of `12px` if the system language is set to Chinese. For this
	// reason we just double the `font-size` and set it to `20px`.
	//
	// See https://github.com/squidfunk/mkdocs-material/issues/911
	font-size: 125%;

• https://www.reddit.com/r/web_design/comments/ohdxbt/using_percentage_units_in_font_size/

[A3Bagged]

@kamilkrzyskow Thank you for your response, you're right im not looking for Theme Development. If im correct according to the Mkdocs documentation theme development is for building from scratch, im customizing material so theme customization is more what i need.

Mainly what i changed is the extra.css which live sin the docs/ directory and custom homepage within the custom_dir which by default is material:

material/
   ├─ overrides/
   │  ├─ assets/
   │  │  └─ images/
   │  │  └─ stylesheets/
   │  └─ partials/
   │      └─ hero.html
   │      └─ features.html
   │      └─ etc..
   ├─ home.html
   └─ main.html

Im using the partials just like insiders did for the parallax, could be done with having everything inside home.html but this makes reading & changing parts of the homepage easier, also disabling certain parts out of it or adding things.

This however doesnt need to be open to the public (same with if using any other insiders plugin etc)

---

Instead of the theme development, your docs page should be the Publishing guide:

• https://squidfunk.github.io/mkdocs-material/publishing-your-site/

That's what i done in this case, however the overrides folder is still open to the public

I will check with my friend since he knows a whole lot more about github.
I will be reading the links you provided me thanks.

[A3Bagged]

So if i'm understanding correctly, if i do want a change that's not within the theme i make changes to the src. Then build (package) the theme and pip install from that instead of the original mkdocs-material.

Or perhaps (not sure if possible) upload the editted build on a private repo and change the pip install git to the private repo, i think?

[kamilkrzyskow]

So if i'm understanding correctly, if i do want a change that's not within the theme i make changes to the src. Then build (package) the theme and pip install from that instead of the original mkdocs-material.

Yes, if the changes require a rebuild in the first place. Have you changed any of the SCSS files?

Or perhaps (not sure if possible) upload the editted build on a private repo and change the pip install git to the private repo, i think?

You can look at the workflow files from the theme itself, as they do hold the Insiders files in the other repository, but the documentation build workflow is setup here in this repository and it fetches the files during the github action. But please note this is mostly a "hack" for the theme itself, since your documentation project is exactly that, a documentation site, it doesn't need to hold any of the theme files in the same repository, so you don't have to sync it during build.

mkdocs-material/.github/workflows/documentation.yml

Lines 76 to 90 in 51e4d4b

	- name: Install Insiders build
	if: github.event.repository.fork == false
	env:
	GH_TOKEN: ${{ secrets.GH_TOKEN }}
	run: |
	# Warning: please don't use this method when installing Insiders from
	# CI! We have to do it this way in order to allow for overrides on our
	# own documentation, but you should stick to the method we recommend
	# in the publishing guide – see https://bit.ly/3zjdJtw
	git clone --depth 1 https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
	pip install -e mkdocs-material-insiders
	cp mkdocs-material-insiders/mkdocs.yml mkdocs.yml
	# echo 'extra_javascript: [${{ vars.CHAT_CLIENT_URL }}]' >> mkdocs.yml
	rm -rf material
	cp -r mkdocs-material-insiders/material material

pip install git+<insiders-repository> is the right direction as per the Publishing Guide 👍

If you think that your maintainers of the documentation page would have a hard time properly installing the Insiders version, or you believe managing private access to those files could become some kind of ordeal, then I think you could include the built minified / obfuscated assets for the home page in your public repository with proper license mention.

The minified HTML source for the theme is also public:

• view-source:https://squidfunk.github.io/mkdocs-material/

or the minified CSS for the parallax is also public on the front page (link might change due to hash later):

• https://squidfunk.github.io/mkdocs-material/assets/stylesheets/home.ac698b0a.min.css

So exposing such files in the same way won't change a thing imo ✌️

[A3Bagged]

Yes, if the changes require a rebuild in the first place. Have you changed any of the SCSS files?

No, there's too much to go over, however i did notice the use of @import which is kinda outdated (still works though).
I'd rather add additional scss or even css files toe extend the theme rather than change eveything.
Perhaps that's the best route after all, if there are any updates in the future merging would be a lot easier with extends than to change the source.

pip install git+<insiders-repository> is the right direction as per the Publishing Guide 👍

If you think that your maintainers of the documentation page would have a hard time properly installing the Insiders version, or you believe managing private access to those files could become some kind of ordeal, then I think you could include the built minified / obfuscated assets for the home page in your public repository with proper license mention.

That's why i asked. until shortly i didnt notice that the material for mkdocs doesn't get cloned into the repo you build with the ci.yml.
that's what i first thought so i was wondering "well how do people publish insiders then if those files get pushed?"
Turns out i was looking at the wrong thing, cloning the material repo and publishing that instead of the bare minimum needed.

Yesterday i started a fresh install on a new test repo, only making and changing the files needed (partials for homepage etc) without all the rest and this works alright, athough i cant seem to use any of the insiders plugins from a mkdocs new . install without adding them manually for using mkdocs serve perhaps i can add them manually and remove them before publish or even exclude it with .gitignore but that's something to research another day.

The minified HTML source for the theme is also public:

• view-source:https://squidfunk.github.io/mkdocs-material/

or the minified CSS for the parallax is also public on the front page (link might change due to hash later):

• https://squidfunk.github.io/mkdocs-material/assets/stylesheets/home.ac698b0a.min.css

So exposing such files in the same way won't change a thing imo ✌️

Yeah i know, if people want they can steal anything. The minified code can even be run through a beautifier.
At least if they do they get a hold of the .css and not the pre formatted scss for example 😆

Thank you.

[kamilkrzyskow]

cant seem to use any of the insiders plugins

Perhaps you need to use the --force-reinstall flag during the Insiders installation, like mentioned here in the upgrade docs:

• https://squidfunk.github.io/mkdocs-material/insiders/upgrade/#how-to-upgrade-pip-upgrade-to-latest-development