|
On 9/24/19 11:06 PM, Randy Barlow
wrote:
On Tue, 2019-09-24 at 16:55 -0400, Randy Barlow wrote:On Tue, 2019-09-24 at 15:20 +0200, Petr Bokoc wrote:Sure! You guys are the experts and you know all about what people need to do and how to do it, so it's best if you do most of the actual content writing; I'm happy to help you with markup, structure and that sort of stuff. Some basic info about how the docs site works is in the template repo README: https://pagure.io/fedora-docs/template Once we have something publishable I'll add it to the site and link it from https://docs.fedoraproject.org/en-US/engineering/Great! Do you have a suggestion for a particular git repository to be used for this, or should we start a new git repository just for these docs?Or do you recommend using the repo that pingou suggested: https://pagure.io/infra-docs-fpo Pingou's repo is OK to use. I
created a new module for these docs within it; the table of
contents of this module will appear below the main module's
navigation. We can easily change that later if we need to.
Any sources go into the module's
pages/ directory, and don't forget to link them
(xref:filename[link text]) in the module's nav.adoc, otherwise
they'll be built and available if you have the page URL, but
won't be linked in the sidebar.
If you want to use any images, put
them in assets/images/ and use
"image::only-the-filename-without-directories[optional alt
text]".
Each source file in pages/ needs to
start with a level 1 heading ("= Heading", like index.adoc
does), otherwise Antora will still build it but all sorts of
weird stuff will start happen.
If you want to reuse a snippet of
text (like, say, have some kind of a warning box in multiple
places but stored only in a single source so you can easily edit
it once and see the change everywhere), make a
modules/communishift/partials/ directory and put .adoc files
containing only these reusable snippets in them (no heading on
top or anything), and include them in other sources with
"include::partial$filename.adoc[]". These partials won't be
built as separate pages, Antora ignores them unless they're
included somewhere else, so you won't end up with people coming
in from google and finding only the snippet.
Generally don't worry about markup
too much, once you're at least somewhat done I'll go through
everything.
Cheers,
Petr
|
_______________________________________________ infrastructure mailing list -- infrastructure@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to infrastructure-leave@xxxxxxxxxxxxxxxxxxxxxxx Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/infrastructure@xxxxxxxxxxxxxxxxxxxxxxx
