Teething problems !

Project Management and Documentation, Part 1

I spent the first few days wandering between the links and resources. Documenting the way-finding and decisions behind choosing "How to document" is extremely meta so I will just describe whatever I come up with post fact. Currently I am just struggling with How to create the webpages in a fast and convenient method.

What have I done so far : - Attended the Wednesday session - Attended the Saturday GOT session

  • Task 1 : Agreements

    • Downloaded the 3 agreement documents,
    • reuploaded them to my repo,
    • edited them to add my name in there,
    • moved them into a separate sub-directory for the sake of organization I would have liked to try adding them directly to my repo through some clone-shone mojo but it seemed faster to d/l and re-upload, plus I realised I wold have to edit them to sign them so files staying linked would definitely not be the solution even if that kind of thing worked. #AskAmit if this was possible

  • Compiled all the relevant links to a Notion page, to which I will keep adding. These include

    • my Gitlab editor page
    • my "deployed" "rendered" page
    • the Fab2023 schedule with all the sublinks and pages that I will go through selectively/step-by-step
    • lots of resource, examples, and other random links tossed around during the sessions/suggested by various people

The story so far : I am commfortable with markdown, I've used it before on GitHub I do not want te be editing Raw HTML (unless absloutely necessary, and even then I suspect it may not work given that static sites are probably re-generated often)

MkDocs is useful to create markdown docus, I guess /shrug/ Is this correct ? #AskAmit MkDocs allows you to apply a theme, to prettify your pages.

I need to find a workflow that goes Markdown -> pretty HTML, and uploads this HTML to the repo My suspicion : - edit in VSCode to make .md files - render .md files using MkDocs + applied theme to generate HTML offline on my laptop - keep syncing the folder with the repo - Gitlab will render the site as usual

If this is correct, my bottlenecks/questions : - install VSCode (unless Atom is ok) - can I get away without using MkDocs and write markdown directly somewhere, like I am doing on my github sandbox site ?

  • (I have forgotten how I do it on the sandbox site as well, and don't rememeber where I kept the notes) - but my few questions were

    • What's the priority of index.html, index.md, readme.md, etc and other files in the same folder
    • How do I deploy the github.io files as pages on github.com, and sub-pages, etc
    • I had this figured out at one point so I'll just go jog my memory once I'm done with this stream-of-consciousness brain-venting+figuring out loud

  • for now I am just creating a new folder within the assignements page and writing THIS markdown file so I can get the content down atleast, while I figure the How-To, and possibly since it's the only file in the folder, it renders as the page as well ? fingers crossed.

Update 01

Things I have learnt in the past 5 minutes - refer to the markdown formatting guide, it is good to remind yourself from time to time - Folder + week01.md does not work, the file doesn't render in Gitlab - Folder + readme.md renders the readme file when you enter the folder on Gitlab

More questions : I am not necessarily wedded to markdown if I can figure a good workflow that takes my content and creates HTML out of it - whether it's a WYSIWYG editor or whatever, as long as my major task is the content, and the formatting is figured maybe once, likely as a theme file. I am realising what I want is basically MS Word with Styles. Oh dear. This can be very good or very bad.

Update 02

  • Added the link to the Week01/readme.md file to the week01.html page
  • /Folder/file.md is RELATIVE to ROOT links, didn't work
  • Folder/file.md is relative to current position and does work to access file
  • Unfortunately that just gets you to download the readme.md file instead of opening it as a page

Update 03

I'm making the more functional updates now, for now I guess I have explored the render + structure issues enough to poke around and #AskAmit tomorrow - Added actual name to the html files in title, heading and footer. - Updated the about.html page. PLEASE UPDATE THAT OLD COPYPASTA DESCRIPTION AND DON'T BE CAMPING AT THE INTERSECTION. That shit got old. Add images and jazz. - Added brief material to the Final Project page. Sorely missed markdown while writing pure HTML.