search

braydie / HowToBeAProgrammer

A guide on how to be a Programmer - originally published by Robert L Read
https://braydie.gitbooks.io/how-to-be-a-programmer/content/
15.9k stars 1.34k forks source link

Add semantic version numbers to pages #75

Closed braydie closed 8 years ago

braydie commented 8 years ago

As per @xmalinov - https://github.com/braydie/HowToBeAProgrammer/issues/45#issuecomment-171892970 for keeping translated versions of the guide in sync

braydie commented 8 years ago

Github-flavoured markdown doesn't support metadata, so it looks like I may need to add inline HTML into each file for the version number, either using <meta name="version" content="1.0.0" /> or something bespoke like <version number="1.0.0" />. Has anyone come across this sort of thing before or know of a better approach for including version numbers?

ajsebastian commented 8 years ago

Hi! If you still need help doing this I would be more than willing to run through and insert this into the files.

braydie commented 8 years ago

hey @ajsebastian, the issue that I've yet to resolve is how to add the version numbers so that they don't impact the readability of the pages on github or gitbook -- ideally, I want to be able to add the version numbers as metadata so that it doesn't render on the page

ajsebastian commented 8 years ago

@braydie That makes a lot more sense. After looking into it for a while it seems that the best way to add comments to markdown files which won't appear in the github page (it will still show in the raw data) is to format your comments like this: [//]: # (This may be the most platform independent comment) . Everything inside of the parenthesis will not show unless you look at the raw data. I tested on a markdown file in a test directory here: https://github.com/ajsebastian/ajsebastian.github.io/blob/master/Comment%20showcase.md and it seems to work in the Github environment. You can see the comments by going to the raw or blame tabs. Let me know if this helped!

Edit: Also works with Gitbook as well.

ajsebastian commented 8 years ago

If you give me the version numbers and are satisfied with the comment method i could take this issue and update all of the files ASAP.

ajsebastian commented 8 years ago

I submitted a pull request of a version of the project where every file has a version number comment at the top. Hope this was helpful.

braydie commented 8 years ago

@ajsebastian that is awesome! I think there are probably a few differences between the English and Chinese version at present just down to natural drifting within each section, which we will just have to accept for the time being. Thank you so much for figuring this out! I'm tied up this weekend but will review and merge in the coming week!