Add Github flavored Markdown syntax for .wiki files #5

Closed
wants to merge 2 commits into
from

Conversation

Projects
None yet
4 participants
Contributor

mehlah commented Jun 13, 2011

Should we keep files for li3_docs or rather update it to parse .md files ?

Owner

nateabele commented Jun 13, 2011

I actually don't see much purpose in this. The root readme file was converted for the repository main page, but the rest were written for li3_docs. Updating those would probably mean changing the documentation standard, and converting the API docs for the entire core, which is just not worth it. Thanks anyway for the efforts.

nateabele closed this Jun 13, 2011

Owner

davidpersson commented Jun 14, 2011

As simple as transitioning all namespace documents and READMEs (by changing the suffix from wiki to md) seems, changes like this lead to an inconsistent state across projects where some inevitably still use wiki while others are already at md.

The original need for changing the suffix comes from the way GitHub deals with such documents. This seems to be a little silly at first.

However I'd see there's something to win here as changing the suffix to .md would lead to:

  • Enabling rendering of namespace documents within github and the repo browser.
  • Synchronizing readme.wiki with README.md would go away.
  • Standardization of the suffix. md would be the suffix I personally would use for markdown files. How much there is a standard for this is still debatable.

Potential solutions for transitioning include:

  • Modifying li3_docs to look for wiki and md or make the suffix configurable.
  • While we're moving projects over to gh change the suffix of the documents.
  • Have a tool doing that for you:
for FILE in $(find . -name '*.wiki'); do git mv $FILE ${FILE/.wiki/.md}; done

All in all I would vote for finding out what we would deem official/standard, changing the suffix.
In the same spirit we should discuss standard project files casing suffix i.e. LICENSE.txt README.txt.

Owner

nateabele commented Jun 14, 2011

Unfortunately, the issue isn't as simple as changing a file extension. If it was, I would be all for it. GitHub seems to use a fundamentally different Markdown format than we do, and changing that in all API docblocks in the core and across all applications is not my idea of a good time. :-) Besides, I think the format we have now reads better within the context of source code.

That said, I'm more than happy to be proven wrong. If we can find some middle ground between our format and theirs, great. @mehlah: I know GitHub actually does support multiple markup formats (https://github.com/github/markup). Could you do some investigating and see if they actually do support our flavor and I just overlooked it or didn't do it right? If so, please reopen the issue and let us know whatever you find.

Thanks!

Contributor

mehlah commented Jun 14, 2011

@nateabele I'll check on that

This was referenced Feb 16, 2012

Member

d1rk commented Sep 26, 2012

@mehlah any information on the github/markup project? I see Nates points as valid, but also would like to see the benefit of what we would have if .md would be the suffix.

Owner

nateabele commented Sep 26, 2012

If all we have to do is change a file extension, awesome. :-)

Member

d1rk commented Sep 26, 2012

Well, i would go for that solution, even if github does not render everything as intended or done by li3_docs. At least, it is more readible than the standard .wiki files.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment