Project Management and Documentation
BAT files
While I have expressed a preference for the GUI, I did pull some CLI tricks to make life simpler in the long run.
I created *.bat files containing the mkdocs build and mkdocs serve commands, along with the relevant Change Directory commands, so I would just need to double-click and run them to serve the mkdocs website on the local server instead of going to CMD and typing it out. Very convenient.
run Mkdocs serve.bat
cd E:\__SnowCrash\_FabSite\fabDocu
mkdocs serve
run Mkdocs build.bat
cd E:\__SnowCrash\_FabSite\fabDocu
mkdocs build
Resizing Images in MKDocs
Once I was reasonably sure that the pipeline was working, my .md files were all upped-and-loaded, and generally things were fine, I decided to clean up my images workflow. But first, I needed to resize the images on the page.
I had run through a lot of online resources, and had come to the following conclusions :
- markdown allows images, ofcourse, but you can't resize theme
- to set images with a particular size, you need to use raw HTML tags to embed images and specify width, height attributes
I tried various ways of defining the HTML tag (there's only so many ways to write <src = "this/is/my/path.jpg">) but nothing seemed to work. Finally, I had every option in the code and I sent a screenshot with an appeal to help to the Regional Whatsapp group.
Deepu responded in a bit, with something that seemed to work for him. Unfortunately, it didn't for me. I suspected he had other plugins or extensions active, having seen that such things exist from AS's mkdocs.yml as well as all my adventures in getting MkDocs to work earlier. Deepu very kindly sent me a picture of his mkdocs.yml file and there was something there that seemed to fit the bill - an extension called list_attr.
I looked it up and added it to my yml file, and Lo and Behold, my images resized !
Internal Bookmarks
To link to points within an MD page, follow the address of the page with a single # and the rest of the heading in small letters, no caps and replacing spaces with "-"
This was thanks to This Stackoverflow Page as well as This One
Embedding videos in MKDocs
One option is the basic HTML embed.
The Kannai Fablab has some instructions
However, if you want a more streamlined approach, there is an extension you can use.
MKDocs Video
Following the insructions on the page, I installed the plugin, as well as added it to my mkdocs.yml file.
You will also have to add this to the requirements.txt file in your repo so that your GitLab website also has the same functionality. To do this, first find the correct version number, etc by running pip freeze > requirements.txt and then copying the relevant lines to your GitLab website's requirements.txt file.
Requirements.txt file
Learn more about the requirements.txt file here :
Code blocks in Markdown
Inline : Use backticks ` around the code content to format it as code
Blocks : Surround your block of code with a line of three backticks before and after, ``` like this.
this is formatted as code
and so is this
You can also indent the text with 3 tabs to format it as code.
like This
or This
How to format code in markdown
Things I learnt
- Images can't be resized in markdown.
- Unless you use an extension called List Attributes (list_attr) Attribute Lists
- Double spaces at the end of a line are a really effective new-line break in markdown.
- Careful with the branch and repo names.
- Clean up your assorted files and folders for clarity and ease of use, now or later.
Writing Markdown
There are too many tips, tricks and syntaxes to list, that I have referred to over time. But I found the following resources very useful and frequently used.
Markdown Guide - Basic Syntax for general formatting whenever I needed clarity.
Markdown Guide - Extended Syntax for creating tables and such-like.
Szymon Krajewski for the 2 spaces = new line nugget.
Daring Fireball's Markdown Syntax Page
Commonmark Markdown Tutorial