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

doc toolchain enhancements ( <title> tag, etc.) #505

Closed
andychu opened this issue Oct 4, 2019 · 4 comments
Closed

doc toolchain enhancements ( <title> tag, etc.) #505

andychu opened this issue Oct 4, 2019 · 4 comments
Labels
documentation pending-release

Comments

@andychu
Copy link
Contributor

andychu commented Oct 4, 2019

e.g. the manual and

https://www.oilshell.org/release/0.7.pre5/doc/eggex.html

Someone mentioned this on reddit too.
tekknolagi added a commit to tekknolagi/oil that referenced this issue Oct 22, 2019
@tekknolagi
Add title to docs
a4c42ab 
Fixes oils-for-unix#505
@tekknolagi tekknolagi mentioned this issue Oct 22, 2019
Closed
@andychu
Copy link
Contributor Author

andychu commented Oct 22, 2019

Also: link to the original .md file in Github

@andychu
Copy link
Contributor Author

andychu commented Oct 22, 2019 •
edited
Loading

From my notes:

  • cmark.py: change #toc_01 to #array-must-be-explicit like Github. But only for new docs?
  • add <title> to manual and such
  • doc update: show GITHUB SOURCE LINK in docs, and accept pull requests.
  • make the manual HTML semantic
    • use h1, h2, h3 properly, with stylesheet
    • right now I use h3 and h4. Probably need a flag to cmark.py to also accept h2 and h3.

The title and source URL imply we want some kind of "front matter" over the pure markdown.

More:

  • link back to the doc index

  • toolchain can insert output of running Oil (or assert the output if it's provided)

  • more use for metadata:

    • css file
    • and javascript? If we ever need that
    • blog:
      • date (created and last updated)
      • tags for categorization
      • comments URL
      • reuse blog.py? split it into JSON?

@andychu
Copy link
Contributor Author

andychu commented Oct 22, 2019

These kinds of book don't have an explicit title in the markdown. Instead they use JavaScript to change the title tag to the section header. Not sure if we want that.

https://doc.rust-lang.org/book/ch06-00-enums.html

@andychu andychu changed the title docs need <title> tag doc toolchain enhancements ( <title> tag, etc.) Oct 28, 2019
andychu pushed a commit that referenced this issue Oct 29, 2019
[doc] Use semantic headers: h1, h2, h3
f5bb8ba 
Related to issue #505.
andychu pushed a commit that referenced this issue Oct 29, 2019
[doc] Generate pretty href/internal anchors from section headings.
1aa3904 
It's similar to what Github does when rendering Markdown as HTML.

The devtools/cmark.py tool is used for both the blog and the Oil docs.

Addresses issue #505.
@andychu
Copy link
Contributor Author

andychu commented Nov 11, 2019

Released with 0.7.pre6 : https://www.oilshell.org/release/0.7.pre6/

@andychu andychu closed this as completed Nov 11, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation pending-release
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add title to docs tekknolagi/oil
1 participant
@andychu