Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Move to using markdown and better use of templates #324

Closed
levitte opened this issue May 5, 2022 · 6 comments
Closed

Move to using markdown and better use of templates #324

levitte opened this issue May 5, 2022 · 6 comments

Comments

@levitte
Copy link
Member

levitte commented May 5, 2022

Our current web pages all contain a lot of boilerplate... they all start with this (hopefully and with varying titles):

<!DOCTYPE html>
<html lang="en">
<!--#include virtual="/inc/head.shtml" -->

<body>
  <!--#include virtual="/inc/banner.shtml" -->

  <div id="main">
  <div id="content">
    <div class="blog-index">
      <article>
        <header><h2>Welcome to OpenSSL!</h2></header>
        <div class="entry-content">

... and all end with this (hopefully and with varying breadcrumbs):

        </div>
        <footer>
          You are here: <a href="/">Home</a>
          <br/><a href="/sitemap.txt">Sitemap</a>
        </footer>
      </article>
    </div>
    <!--#include virtual="sidebar.shtml" -->
  </div>
</div>

<!--#include virtual="/inc/footer.shtml" -->
</body>
</html>

We now have mechanisms in place, when we can get rid of all this repeated boilerplate, and move to base pages on markdown (do note that markdown files can contain HTML, so a valid lazy move could be to simply rename current .html files and drop all the boilerplate).

It's necessary to create a file dirdata.yaml with the metadata (content corresponding to sidebar.shtml and the breadcrumbs that are currently repeated in every .html file), see policies/dirdata.yaml as an example:

https://github.com/openssl/web/blob/79905834dd07275c013857b7cd9b92f14c292e35/policies/dirdata.yaml

This doesn't have to be done all in one go, but should be encouraged.
@levitte
Copy link
Member Author

levitte commented May 5, 2022 •
edited
Loading

As an example, the top index.html could be converted to the following index.md:

---
title: Welcome to OpenSSL!
---
The OpenSSL Project develops and maintains the OpenSSL software - a robust,
commercial-grade, full-featured toolkit for general-purpose cryptography and
secure communication. The project's technical decision making is managed by
the [OpenSSL Technical Committee](/community/otc.html) (OTC) and the project
governance is managed by
the [OpenSSL Management Committee](/community/omc.html) (OMC).
The project operates under formal [Bylaws](/policies/omc-bylaws.html). 

For more information about the team and community around the project, or to
start making your own contributions, start with the [community](/community)
page. To get the latest news, download the source, and so on, please see the
sidebar or the buttons at the top of every page.

OpenSSL is licensed under an Apache-style license, which basically means
that you are free to get and use it for commercial and non-commercial
purposes subject to some simple license conditions.

For a list of vulnerabilities, and the releases in which they were found and
fixes, see our [Vulnerabilities](news/vulnerabilities.html) page.

### Latest News

<table class="newsflash" width="90%">
<!--#include virtual="newsflash.inc"-->
<tr><td class="d"><a href="news">More...</a></td><td class="t"></td></tr>
</table>
<p>&nbsp;</p>

<!--#include virtual="/inc/legalities.shtml" -->

@levitte
Copy link
Member Author

levitte commented May 5, 2022

At the very least, new pages should be made in Markdown... as it turns out that we've already started doing, see #313

@levitte levitte mentioned this issue May 5, 2022
Closed
@levitte
Copy link
Member Author

levitte commented May 5, 2022

Note: for rendering, pandoc is used. It understands github markdown, but not only.

levitte added a commit to levitte/openssl-web that referenced this issue Jul 11, 2022
@levitte
Convert all top .html to .md
9da6877 
Pandoc makes this really easy:

    pandoc -f html -t markdown -o index.html index.md

Only very minute small manual adjustments are needed afterwards.

Partial fix of openssl#324
@levitte levitte mentioned this issue Jul 11, 2022
Closed
levitte added a commit to levitte/openssl-web that referenced this issue Jul 11, 2022
@levitte
Convert all community/*.html to .md
16a5fef 
Partial fix of openssl#324
@levitte levitte mentioned this issue Jul 11, 2022
Closed
levitte added a commit to levitte/openssl-web that referenced this issue Jul 11, 2022
@levitte
Convert all community/*.html to .md
378202a 
Partial fix of openssl#324
levitte added a commit to levitte/openssl-web that referenced this issue Jul 11, 2022
@levitte
Convert all docs/*.html to .md
fc33749 
We only take the easy parts, and leave manual page generation files alone.

Partial fix of openssl#324
@levitte levitte mentioned this issue Jul 11, 2022
Closed
levitte added a commit to levitte/openssl-web that referenced this issue Jul 11, 2022
@levitte
Convert news/*.html to .md
58ac597 
Partial fix of openssl#324
@levitte levitte mentioned this issue Jul 11, 2022
Closed
levitte added a commit to levitte/openssl-web that referenced this issue Jul 11, 2022
@levitte
amend! Convert all docs/*.html to .md
6077ace 
Convert docs/*.html to .md

We only take the easy parts, and leave manual page generation files alone.

Partial fix of openssl#324
levitte added a commit to levitte/openssl-web that referenced this issue Jul 11, 2022
@levitte
amend! Convert news/*.html to .md
7562ac8 
Convert all news/*.html to .md

Partial fix of openssl#324
levitte added a commit to levitte/openssl-web that referenced this issue Jul 11, 2022
@levitte
Convert all policies/*.html to .md
3c38b1d 
Partial fix of openssl#324
@levitte levitte mentioned this issue Jul 11, 2022
Closed
levitte added a commit to levitte/openssl-web that referenced this issue Jul 12, 2022
@levitte
Convert all policies/*.html to .md
204e0bb 
Partial fix of openssl#324
levitte added a commit to levitte/openssl-web that referenced this issue Jul 12, 2022
@levitte
amend! Convert all support/*.html to .md
73b9b71 
Convert all support/*.html to .md

Partial fix of openssl#324
levitte added a commit to levitte/openssl-web that referenced this issue Jul 12, 2022
@levitte
Convert all source/*.html to .md
046e437 
Partial fix of openssl#324
levitte added a commit to levitte/openssl-web that referenced this issue Jul 12, 2022
@levitte
Convert all source/old/*.html to .md
3b7d64d 
Partial fix of openssl#324
@levitte levitte mentioned this issue Jul 12, 2022
Closed
@levitte
Copy link
Member Author

levitte commented Jul 12, 2022

Work has happened. I've merged all the PRs into a branch that is currently used on https://beta.openssl.org
I haven't looked yet, but will do so soon.

openssl-machine pushed a commit that referenced this issue Jul 15, 2022
@levitte
Convert all community/*.html to .md
a98b9fc 
Partial fix of #324

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from #344)
openssl-machine pushed a commit that referenced this issue Jul 15, 2022
@levitte
Convert all news/*.html to .md
8e8e8ef 
Partial fix of #324

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from #346)
openssl-machine pushed a commit that referenced this issue Jul 15, 2022
@levitte
Convert all support/*.html to .md
d67adbc 
Partial fix of #324

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from #348)
openssl-machine pushed a commit that referenced this issue Jul 15, 2022
@levitte
Convert all top .html to .md
364ddb0 
Pandoc makes this really easy:

    pandoc -f html -t markdown -o index.html index.md

Only very minute small manual adjustments are needed afterwards.

Partial fix of #324

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from #343)
levitte added a commit to levitte/openssl-web that referenced this issue Jul 15, 2022
@levitte
Convert all docs/*.html to .md
a54b8f6 
We only take the easy parts, and leave manual page generation files alone.

Partial fix of openssl#324
levitte added a commit to levitte/openssl-web that referenced this issue Jul 15, 2022
@levitte
amend! Convert all docs/*.html to .md
0e7fd31 
Convert docs/*.html to .md

We only take the easy parts, and leave manual page generation files alone.

Partial fix of openssl#324
levitte added a commit to levitte/openssl-web that referenced this issue Jul 15, 2022
@levitte
Convert all policies/*.html to .md
e39e3a9 
Partial fix of openssl#324
levitte added a commit to levitte/openssl-web that referenced this issue Jul 15, 2022
@levitte
Convert all source/*.html to .md
692222d 
Partial fix of openssl#324
levitte added a commit to levitte/openssl-web that referenced this issue Jul 15, 2022
@levitte
Convert all source/old/*.html to .md
6b963ca 
Partial fix of openssl#324
levitte added a commit to levitte/openssl-web that referenced this issue Jul 15, 2022
@levitte
Convert all policies/*.html to .md
5d1140e 
Partial fix of openssl#324
levitte added a commit to levitte/openssl-web that referenced this issue Jul 15, 2022
@levitte
Convert docs/*.html to .md
4a54673 
We only take the easy parts, and leave manual page generation files alone.

Partial fix of openssl#324
openssl-machine pushed a commit that referenced this issue Jul 16, 2022
@levitte
Convert all policies/*.html to .md
d24e992 
Partial fix of #324

Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from #347)
levitte added a commit to levitte/openssl-web that referenced this issue Jul 17, 2022
@levitte
Convert docs/*.html to .md
54b59a4 
We only take the easy parts, and leave manual page generation files alone.

Partial fix of openssl#324
levitte added a commit to levitte/openssl-web that referenced this issue Jul 17, 2022
@levitte
Convert all source/*.html to .md
4265fc9 
Partial fix of openssl#324
levitte added a commit to levitte/openssl-web that referenced this issue Jul 17, 2022
@levitte
Convert all source/old/*.html to .md
ceac7c5 
Partial fix of openssl#324
@levitte
Copy link
Member Author

levitte commented Jul 20, 2022 •
edited
Loading

PRs:

openssl-machine pushed a commit that referenced this issue Jul 20, 2022
@levitte
Convert docs/*.html to .md
9d6ac3f 
We only take the easy parts, and leave manual page generation files alone.

Partial fix of #324

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from #345)
openssl-machine pushed a commit that referenced this issue Jul 20, 2022
@levitte
Convert all source/*.html to .md
239296d 
Partial fix of #324

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from #349)
openssl-machine pushed a commit that referenced this issue Jul 20, 2022
@levitte
Convert all source/old/*.html to .md
fe6c01f 
Partial fix of #324

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from #349)
@levitte
Copy link
Member Author

levitte commented Jul 20, 2022

All associated PRs merged. Closing

@levitte levitte closed this as completed Jul 20, 2022
mkoci-koca pushed a commit to mkoci-koca/web that referenced this issue Oct 6, 2022
@levitte
Convert all community/*.html to .md
6159826 
Partial fix of openssl#324

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from openssl#344)
mkoci-koca pushed a commit to mkoci-koca/web that referenced this issue Oct 6, 2022
@levitte
Convert all news/*.html to .md
0f78645 
Partial fix of openssl#324

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from openssl#346)
mkoci-koca pushed a commit to mkoci-koca/web that referenced this issue Oct 6, 2022
@levitte
Convert all support/*.html to .md
964f75b 
Partial fix of openssl#324

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from openssl#348)
mkoci-koca pushed a commit to mkoci-koca/web that referenced this issue Oct 6, 2022
@levitte
Convert all policies/*.html to .md
eb6a29d 
Partial fix of openssl#324

Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from openssl#347)
mkoci-koca pushed a commit to mkoci-koca/web that referenced this issue Oct 6, 2022
@levitte
Convert docs/*.html to .md
17c159d 
We only take the easy parts, and leave manual page generation files alone.

Partial fix of openssl#324

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from openssl#345)
mkoci-koca pushed a commit to mkoci-koca/web that referenced this issue Oct 6, 2022
@levitte
Convert all source/*.html to .md
9527fa4 
Partial fix of openssl#324

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from openssl#349)
mkoci-koca pushed a commit to mkoci-koca/web that referenced this issue Oct 6, 2022
@levitte
Convert all community/*.html to .md
17b4f90 
Partial fix of openssl#324

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from openssl#344)
mkoci-koca pushed a commit to mkoci-koca/web that referenced this issue Oct 6, 2022
@levitte
Convert all news/*.html to .md
0016c43 
Partial fix of openssl#324

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from openssl#346)
mkoci-koca pushed a commit to mkoci-koca/web that referenced this issue Oct 6, 2022
@levitte
Convert all support/*.html to .md
9078971 
Partial fix of openssl#324

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from openssl#348)
mkoci-koca pushed a commit to mkoci-koca/web that referenced this issue Oct 6, 2022
@levitte
Convert all policies/*.html to .md
a5a03ea 
Partial fix of openssl#324

Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from openssl#347)
mkoci-koca pushed a commit to mkoci-koca/web that referenced this issue Oct 6, 2022
@levitte
Convert docs/*.html to .md
7df57c2 
We only take the easy parts, and leave manual page generation files alone.

Partial fix of openssl#324

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from openssl#345)
mkoci-koca pushed a commit to mkoci-koca/web that referenced this issue Oct 6, 2022
@levitte
Convert all source/*.html to .md
00476c3 
Partial fix of openssl#324

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from openssl#349)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@levitte