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.

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

Update Asciidoc markup example with safe defaults #24920

Merged
merged 2 commits into from
May 25, 2023

Conversation

omenos
Copy link
Contributor

@omenos omenos commented May 24, 2023

The cheat sheet uses the asciidoc markup language to demonstrate how to set up third party markup renderers. The current example has the following issues:

  • It promotes a legacy tool that does not handle modern AsciiDoc specifications
  • It does not account for embedded preview renders
  • It has no safety restrictions

By switching to asciidoctor, uses are suggested to utilize de facto/standard tooling for AsciiDoc.

The --embedded parameter will strip out HTML tags that contain the document (such as <html></html>) which aren't necessary for the render, and actually end up as text in the document if left in.

The --safe-mode parameter (of which there are several profiles) imposes certain policies on the files it ingests and what the resulting output looks like. GitHub itself uses the secure profile (the highest), which can be a good starting point for those who are uncertain of what to do. By default, if no mode is specified when asciidoctor runs it defaults to unsafe, i.e. no safety guidelines at all.

- Change from 'asciidoc' to 'asciidoctor' for rendering.
- GitHub renders previews under the "secure" profile. This is a
  reasonable default to demonstrate for those who may not be well
  versed in what Asciidoc can do or are not advanced sysadmins.
- Add embedded parameter to strip out document containing tags that
  will otherwise be displayed in text form when rendered.
@GiteaBot GiteaBot added the lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. label May 24, 2023
@pull-request-size pull-request-size bot added the size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. label May 24, 2023
@GiteaBot GiteaBot added lgtm/need 1 This PR needs approval from one additional maintainer to be merged. and removed lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. labels May 24, 2023
@lunny lunny added the type/docs This PR mainly updates/creates documentation label May 24, 2023
Copy link
Member

@techknowlogick techknowlogick left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@GiteaBot GiteaBot added lgtm/done This PR has enough approvals to get merged. There are no important open reservations anymore. and removed lgtm/need 1 This PR needs approval from one additional maintainer to be merged. labels May 25, 2023
@techknowlogick techknowlogick added the reviewed/wait-merge This pull request is part of the merge queue. It will be merged soon. label May 25, 2023
@techknowlogick techknowlogick enabled auto-merge (squash) May 25, 2023 01:23
@techknowlogick techknowlogick merged commit d7e669c into go-gitea:main May 25, 2023
@GiteaBot GiteaBot added this to the 1.20.0 milestone May 25, 2023
@GiteaBot GiteaBot removed the reviewed/wait-merge This pull request is part of the merge queue. It will be merged soon. label May 25, 2023
zjjhot added a commit to zjjhot/gitea that referenced this pull request May 25, 2023
* upstream/main: (21 commits)
  `zh-cn` translation for usage docs (go-gitea#24897)
  Add chinese documentations for installation (go-gitea#24904)
  Improve RunMode / dev mode (go-gitea#24886)
  Add chinese documentations for `Packages` (go-gitea#24914)
  Rework notifications list (go-gitea#24812)
  New webhook trigger for receiving Pull Request review requests (go-gitea#24481)
  Use file filters action instead of Github's files filter (go-gitea#24877)
  Update Asciidoc markup example with safe defaults (go-gitea#24920)
  Add self to maintainers (go-gitea#23644)
  Create pull request for base after editing file, if not enabled on fork (go-gitea#24841)
  Reduce verbosity of dev commands (go-gitea#24917)
  Merge different languages for language stats (go-gitea#24900)
  Add missing test case and fix typo in tests (go-gitea#24915)
  Improve confusable character string (go-gitea#24911)
  Improve Actions CSS (go-gitea#24864)
  Fix <empty> in administration/config-cheat-sheet.en-us.md (go-gitea#24905)
  Only validate changed columns when update user (go-gitea#24867)
  Rename docs packages title from xxx Packages Repository -> xxx Package Registry (go-gitea#24895)
  Fix can’t move anymore items in repo project boards (go-gitea#24892)
  Make environment-to-ini  support loading key value from file (go-gitea#24832)
  ...

# Conflicts:
#	web_src/css/helpers.css
@go-gitea go-gitea locked as resolved and limited conversation to collaborators Aug 23, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
lgtm/done This PR has enough approvals to get merged. There are no important open reservations anymore. size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. type/docs This PR mainly updates/creates documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants