Restore "edit" button in documentation on the website

[marmarek]

Follow up for #1201 (comment)
@bnvk

[andrewdavidwong]

Seems like a good idea to me. I noticed that we get a fair number of people writing to the mailing list with doc edits rather than submitting pull requests. (But maybe that's just because we tend not to act on pull requests in a timely manner.)

[andrewdavidwong]

Seems like a good idea to me. I noticed that we get a fair number of people writing to the mailing list with doc edits rather than submitting pull requests. (But maybe that's just because we tend not to act on pull requests in a timely manner.)

[andrewdavidwong]

I've created links to view and edit the source of every page using the "doc" layout. These links work beautifully for pages which reside in the primary qubesos.github.io repo, but they fail for all pages which reside in submodules (e.g., qubes-doc).

Current working examples:

• https://www.qubes-os.org/
• https://www.qubes-os.org/downloads/
• https://www.qubes-os.org/en/news/

Current broken examples:

• https://www.qubes-os.org/en/doc/
• https://www.qubes-os.org/en/doc/getting-started/
• https://www.qubes-os.org/en/doc/system-requirements/

(Look in the upper right-hand corner for the "Source" and "Edit" links.)

Options:

1. Create separate layouts for the pages in qubesos.github.io and the pages in submodules, and have the submodule layout use page.relative_path instead of page.path. But we'd still need a way to grab the correct repository_url.
2. Move the pages in qubesos.github.io to qubes-doc, and continue to use one layout (the "doc" layout) for everything, then make the other changes stated in 1.
3. Stop using submodules, and instead have all pages in qubesos.github.io (least likely option).

[andrewdavidwong]

I've created links to view and edit the source of every page using the "doc" layout. These links work beautifully for pages which reside in the primary qubesos.github.io repo, but they fail for all pages which reside in submodules (e.g., qubes-doc).

Current working examples:

• https://www.qubes-os.org/
• https://www.qubes-os.org/downloads/
• https://www.qubes-os.org/en/news/

Current broken examples:

• https://www.qubes-os.org/en/doc/
• https://www.qubes-os.org/en/doc/getting-started/
• https://www.qubes-os.org/en/doc/system-requirements/

(Look in the upper right-hand corner for the "Source" and "Edit" links.)

Options:

1. Create separate layouts for the pages in qubesos.github.io and the pages in submodules, and have the submodule layout use page.relative_path instead of page.path. But we'd still need a way to grab the correct repository_url.
2. Move the pages in qubesos.github.io to qubes-doc, and continue to use one layout (the "doc" layout) for everything, then make the other changes stated in 1.
3. Stop using submodules, and instead have all pages in qubesos.github.io (least likely option).

[marmarek]

As we have only few pages outside of _doc, I think we can have separate layout for them. Or maybe even don't add source/edit button in that layout, only in qubes-doc?

I think this will have another advantage - some pages in main repository looks strange with those buttons - for example home.md or downloads.md.

[marmarek]

As we have only few pages outside of _doc, I think we can have separate layout for them. Or maybe even don't add source/edit button in that layout, only in qubes-doc?

I think this will have another advantage - some pages in main repository looks strange with those buttons - for example home.md or downloads.md.

[bnvk]

As we have only few pages outside of _doc, I think we can have separate layout for them. Or maybe even don't add source/edit button in that layout, only in qubes-doc

I agree with @marmarek about this. I don't think having the
"source' and "edit" buttons on pages other than the docs is that
desirable. Especially once I finish the new site design which
will have a lot graphics and design to it. I don't think we will
want to encourage editing of the home,md file at all!

[bnvk]

As we have only few pages outside of _doc, I think we can have separate layout for them. Or maybe even don't add source/edit button in that layout, only in qubes-doc

I agree with @marmarek about this. I don't think having the
"source' and "edit" buttons on pages other than the docs is that
desirable. Especially once I finish the new site design which
will have a lot graphics and design to it. I don't think we will
want to encourage editing of the home,md file at all!

[andrewdavidwong]

Ok, so only pages in qubes-doc will have source links.

I still can't find any syntax which will allow me to grab the relative path of each .md file without including _doc.

To work around this, I could simply move all the .md files (back) into the "root" of _doc, then reference the file name (instead of the (relative) path).

In favor of this, we could say that any "organization" of the source .md files into subdirectories is pretty artificial in the first place, and a case could be made for putting many of them in several different directories. Not sorting them into subdirectories makes this a non-issue. The drawback (if it even is one) is having a very large number of unsorted .md files in a single directory (notably with no hierarchical organization).

[andrewdavidwong]

Ok, so only pages in qubes-doc will have source links.

I still can't find any syntax which will allow me to grab the relative path of each .md file without including _doc.

To work around this, I could simply move all the .md files (back) into the "root" of _doc, then reference the file name (instead of the (relative) path).

In favor of this, we could say that any "organization" of the source .md files into subdirectories is pretty artificial in the first place, and a case could be made for putting many of them in several different directories. Not sorting them into subdirectories makes this a non-issue. The drawback (if it even is one) is having a very large number of unsorted .md files in a single directory (notably with no hierarchical organization).

[marmarek]

On Sun, Oct 25, 2015 at 05:10:44PM -0700, Axon wrote:

In favor of this, we could say that any "organization" of the source .md files into subdirectories is pretty artificial in the first place, and a case could be made for putting many of them to several different directories. Not sorting them into subdirectories makes this a non-issue. The drawback (if it even is one) is having a very large number of unsorted .md files in a single directory (notably with no hierarchical organization).

I think we should have files layout as close to URLs as possible. If we
have flat URLs scheme, so should be qubes-doc repo.

According to jekyll documentation
it is also possible to override page.path in FrontMatter. But I'm not
sure if we want to go that way, because it will surely desynchronize
over the time (or maybe some script, which will at least verify if those
are set correctly and for example reject such update then?).

Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[marmarek]

On Sun, Oct 25, 2015 at 05:10:44PM -0700, Axon wrote:

In favor of this, we could say that any "organization" of the source .md files into subdirectories is pretty artificial in the first place, and a case could be made for putting many of them to several different directories. Not sorting them into subdirectories makes this a non-issue. The drawback (if it even is one) is having a very large number of unsorted .md files in a single directory (notably with no hierarchical organization).

I think we should have files layout as close to URLs as possible. If we
have flat URLs scheme, so should be qubes-doc repo.

According to jekyll documentation
it is also possible to override page.path in FrontMatter. But I'm not
sure if we want to go that way, because it will surely desynchronize
over the time (or maybe some script, which will at least verify if those
are set correctly and for example reject such update then?).

Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[andrewdavidwong]

I think we should have files layout as close to URLs as possible. If we have flat URLs scheme, so should be qubes-doc repo.

Sounds good to me. That means keeping what we currently have (non-flat URL scheme mirrored by non-flat directory structure).

According to jekyll documentation it is also possible to override page.path in FrontMatter. But I'm not sure if we want to go that way, because it will surely desynchronize over the time (or maybe some script, which will at least verify if those are set correctly and for example reject such update then?).

I tried setting that, but it seemed to have no effect. Maybe I was doing it wrong.

Why would it desynchronize over time, though?

[andrewdavidwong]

I think we should have files layout as close to URLs as possible. If we have flat URLs scheme, so should be qubes-doc repo.

Sounds good to me. That means keeping what we currently have (non-flat URL scheme mirrored by non-flat directory structure).

According to jekyll documentation it is also possible to override page.path in FrontMatter. But I'm not sure if we want to go that way, because it will surely desynchronize over the time (or maybe some script, which will at least verify if those are set correctly and for example reject such update then?).

I tried setting that, but it seemed to have no effect. Maybe I was doing it wrong.

Why would it desynchronize over time, though?

[andrewdavidwong]

If only there were some way to remove the _doc prefix from the output of {{page.relative_path}}, that would work perfectly.

[andrewdavidwong]

If only there were some way to remove the _doc prefix from the output of {{page.relative_path}}, that would work perfectly.

[marmarek]

Why would it desynchronize over time, though?

When someone rename the file without changing FrontMatter.

Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[marmarek]

Why would it desynchronize over time, though?

When someone rename the file without changing FrontMatter.

Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[marmarek]

On Sun, Oct 25, 2015 at 05:32:23PM -0700, Axon wrote:

If only there were some way to remove the _doc prefix from the output of {{page.relative_path}}, that would work perfectly.

Take a look here (IIUC this is the template engine used by jekyll):
https://github.com/Shopify/liquid/wiki/Liquid-for-Designers

Maybe remove_first would work?

Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[marmarek]

On Sun, Oct 25, 2015 at 05:32:23PM -0700, Axon wrote:

If only there were some way to remove the _doc prefix from the output of {{page.relative_path}}, that would work perfectly.

Take a look here (IIUC this is the template engine used by jekyll):
https://github.com/Shopify/liquid/wiki/Liquid-for-Designers

Maybe remove_first would work?

Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[andrewdavidwong]

Marek saves the day, as usual. :)

Looks like everything is working now!

[andrewdavidwong]

Marek saves the day, as usual. :)

Looks like everything is working now!