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