Hi guys, I start verifying how my translation to Russian look at the actual site and found that sometimes links does not displayed on the same place where they are in English docs.
Initially I start from http://cordova.apache.org/docs/ru/edge/guide_platforms_index.md.html where almost all links are broken. I check Italian and French translation, almost all link are in place, so I made assumption that this is probably something wrong with my translation and go to the Github to look at actual .md files. https://raw.githubusercontent.com/apache/cordova-docs/master/docs/en/3.4.0/guide/platforms/index.md https://raw.githubusercontent.com/apache/cordova-docs/master/docs/ru/3.4.0/guide/platforms/index.md I find that no actual links are in the Markdown files. So I assume that some magic in generator is injecting links. I start looking at the cordova-docs/lib folder and don't find anything. I look and joDoc and find that there some function which look across all H1 in all files and use that H1 as link targets in the docs. This is raises following questions in my head: 1. Does I correctly find root cause for broken links in the docs? Could somebody with more knowledge about docs generation confirm that and give more details about how this working, because I may miss some other things. 2. Could we put information for translators how links are generated. That way they will know that all references to other sections should be in the same grammatical case as name of the section. That should be strict rule for transaltors, since it could make content orphaned. Also not technical translators could fix such issue themselves. 3. Could we put cordova-docs/CONTRIBUTING.md in the docs foder, so it could be translated for other languages. Also that file could be separated on stylistical rules, which probably would be universal across all languages, and language specific grammar rules and common grammar/orthographical mistakes which people made. There are more broader question: 4. Do the need such simple system for linking, which could be easily broken when we have 2 files with same H1 content For example would be not uncommon to have sections like 'Overview', 'Upgrading' and so on to appear in multiple areas, like in multiple plugins. For example: http://cordova.apache.org/docs/en/edge/guide_platforms_ios_config.md.htmland this was recorded as CB-5464 (as of 3.1 release).
