[CentOS-docs] Regarding GSoC project

Tue Jun 2 09:41:19 UTC 2015
Dougal Matthews <dougal at dougalmatthews.com>

On 1 June 2015 at 18:24, Karsten Wade <kwade at redhat.com> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 05/30/2015 09:19 AM, Dougal Matthews wrote:
>> An alternative approach would be to build the docs in CI and link
>> to the built version in a comment on both systems.
>
> This is an interesting idea. We'll end up wanting docs to build in the
> CI anyway, so this could be done using e.g. a -draft tag so an initial
> commit can be used to both build drafts and help with the review
> process, then transition to not-draft.
>
> We'd still have MarkDown preview in GitHub, but also have a version
> rendered with the toolchain so we can also be debugging build problems
> as well as content itself.

Yeah, the GitHub preview is what concerns me. They support a number
of things which are non-standard. For example, anything that looks like
a hyperlink is converted into one. Whereas in Markdown you need to use
<http://...> to have it converted. List indentation on GitHub requires
two spaces but the standard is four. There are many others that I can't
think of now too.

This may be fine, I just want to make sure you are aware as it could
cause some confusion. We (MkDocs) get a bug reports sometimes as
people see the render of GitHub and assume that is correct and the
Markdown library we use it wrong.



>
> Regards,
> - - Karsten
> - --
> Karsten 'quaid' Wade        .^\          CentOS Doer of Stuff
> http://TheOpenSourceWay.org    \  http://community.redhat.com
> @quaid (identi.ca/twitter/IRC)  \v'             gpg: AD0E0C41
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.22 (GNU/Linux)
>
> iEYEARECAAYFAlVslWEACgkQ2ZIOBq0ODEEplQCfaIyGOTJ4elJK6aENHU5mvkfk
> OwUAni8y8loHZjtbN+pReYL1A4wXgDZB
> =fueA
> -----END PGP SIGNATURE-----
> _______________________________________________
> CentOS-docs mailing list
> CentOS-docs at centos.org
> http://lists.centos.org/mailman/listinfo/centos-docs