Documentation v3 📝

[sreichel]

Description (*)

Have documentation at one place!

This PR move all docs to docs/content

• https://github.com/OpenMage/magento-lts/blob/main/README.md
  • has a lot content that could move nto smaller files for better maintenance
• https://github.com/OpenMage/magento-lts/tree/main/docs
  • some unorganized files
• https://github.com/OpenMage/OpenMage.github.io (https://www.openmage.org/)
  • duplicate install instructions (see RADME.md)
  • outdated blog section
• https://github.com/OpenMage/documentation (https://openmage.readthedocs.io)
  • outdated/unmaintained

Questions or comments

Can ..

• blog, install section be removed from openmage.org?
• can readthedocs be closed?
• local docs moved - and README cleaned?

There is nothing to do ...

... the worklow creates a branch named gh-pages, that serves the static files ...

... but ...

... the repos setting needs to point githab pages to gh-pages branch.

... and ...

... for local preview ... run mkdocs serve

Comment system

Still points to my repo and needs added here first!

Preview

https://sreichel.github.io/openmage-strict/

[fballiano]

with some tweaks (mainly to the home page) this could replace the main website...

[kiatng]

Is the intention to include documentation (blog) in this repo?

[sreichel]

@kiatng yes, all docs should be here. Think its easier to update/add content here, not in other repos.

[kiatng]

For those who use git to update production, what are the ways to deal with these docs? The docs are unnecessary in production.

[sreichel]

Mhh ... md files are already blocked in .htacces to not expose anything.

With git you dont need no .ddev, .github, and others too .... some additional files do not harm?

[kiatng]

Is it a good idea to prefix a dot to doc, ".doc". Existing server directive already excludes dot files from public access.

Or even better, move to another repo all together?

[sreichel]

Is it a good idea to prefix a dot to doc, ".doc"

Can you please point to it? I dont see it.

Edit: it was a suggestion? I am not sure about this ... having a docs dir seems okay.

Or even better, move to another repo all together?

I read your earlier suggestion about this (related to blog post?), but docs belong here IMHO.

Another repo would make it much harder to maintain it. This is something i am against for 100% With .gitattributes we can excclude files we dont need in prod environment, Having all docs at one repo sounds better to me, We aleady have multible repos, but none is maintained ...

[kiatng]

From PR #1209 : dev/openmage/nginx-frontend.conf and dev/openmage/nginx-admin.conf, e.g.

    # Protect dot files no matter where they are located
    location ~ /\. { return 404; }

I lack the knowledge to review the PR, but it'll be a useful addition. So, someone with better knowledge than me should help to review it.

[sreichel]

In .htaccess we ready have this ...

    <FilesMatch \.(dist|flag|ip|lock|md|neon|sample|sh|yml|yaml)$>
        Order allow,deny
        Deny from all
    </FilesMatch>

... to block access to md files. nginx settings may need adjustments.

[kiatng]

Off topic, I cannot find any solution using .gitattributes, while merging, to not create "new files" (e.g. docs and dev) in production branch. Can you provide some ideas on how to do it?

[sreichel]

#3318

Install via composer should not add excluded files. Using git clone/pull will include them o/c ...

See https://github.com/OpenMage/magento-lts/pull/3659/files#diff-618cd5b83d62060ba3d027e314a21ceaf75d36067ff820db126642944145393e

/docs export-ignore
/docs_includes export-ignore