Skip to content

Commit

Permalink
Update instructions for rich text custom rendering [ci-skip]
Browse files Browse the repository at this point in the history 
Since #43110, we no longer generate `.scss` files by default.

This commit:

* Changes remaining `.scss` filenames to `.css`.
* Updates the instructions for omitting the default Trix styles.
* Eliminates repetitive use of the word "default".
* Reorders the content slightly for better flow.
  • Loading branch information
@jonathanhefner
jonathanhefner committed Feb 13, 2022
1 parent 73e0a9c commit 940980d
Showing 1 changed file with 13 additions and 16 deletions.
29 changes: 13 additions & 16 deletions guides/source/action_text_overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -113,16 +113,8 @@ end

## Rendering Rich Text content

Action Text will sanitize and render rich content on your behalf.

By default, the Action Text editor and content are styled by the Trix defaults.

If you want to change these defaults, remove the `// require "actiontext.scss"`
line from your `application.scss` to omit the [contents of that
file](https://raw.githubusercontent.com/basecamp/trix/master/dist/trix.css).

By default, Action Text will render rich text content into an element that
declares the `.trix-content` class:
By default, Action Text will render rich text content inside an element with the
`.trix-content` class:

```html+erb
<%# app/views/layouts/action_text/contents/_content.html.erb %>
Expand All @@ -131,13 +123,18 @@ declares the `.trix-content` class:
</div>
```

If you'd like to change the rich text's surrounding HTML with your own layout,
declare your own `app/views/layouts/action_text/contents/_content.html.erb`
template and call `yield` in place of the content.
Elements with this class, as well as the Action Text editor, are styled by the
[`trix` stylesheet](https://raw.githubusercontent.com/basecamp/trix/master/dist/trix.css).
To provide your own styles instead, remove the `= require trix` line from the
`app/assets/stylesheets/actiontext.css` stylesheet created by the installer.

To customize the HTML rendered around rich text content, edit the
`app/views/layouts/action_text/contents/_content.html.erb` layout created by the
installer.

You can also style the HTML used for embedded images and other attachments
(known as blobs). On installation, Action Text will copy over a partial to
`app/views/active_storage/blobs/_blob.html.erb`, which you can specialize.
To customize the HTML rendered for embedded images and other attachments (known
as blobs), edit the `app/views/active_storage/blobs/_blob.html.erb` template
created by the installer.

### Rendering attachments

Expand Down

3 comments on commit 940980d

@sedubois
Copy link
Contributor

Choose a reason for hiding this comment

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

@jonathanhefner these are nice doc improvements, however they don't seem to be visible to anybody as the guide is hidden by work_in_progress: true. Could the flag be removed?

@jonathanhefner
Copy link
Member Author

Choose a reason for hiding this comment

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

@sedubois

however they don't seem to be visible to anybody as the guide is hidden by work_in_progress: true.

The guide is listed at https://guides.rubyonrails.org/index.html (albeit labeled as "Work in progress"), and is viewable at https://guides.rubyonrails.org/action_text_overview.html, which is the top search result for "rails action text guide" in Google and Duck Duck Go. "Work in progress" guides are only not listed in the drop-down menu.

Could the flag be removed?

The flag is intended to mark guides that we feel need more polish. Though there is the risk of perpetual beta. I truly don't know where the Action Text guide stands, so I can't say whether the flag should be removed. Has there been any community discussion about it? It would be a good first step to get more eyes on the guide and either find (and fix) flaws or form a consensus of approval.

@sedubois
Copy link
Contributor

@sedubois sedubois commented on 940980d Jun 20, 2022 •
edited

Choose a reason for hiding this comment

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

Personally I only look at the "guides index" dropdown at the top of the page and don't go further down so Action Text not being there is confusing to me. Besides, why do "work in progress" guides get shown in the listing further down, but not in the menu?

I had opened a PR a while back to remove the flag which was closed without discussion. It was said that guide authors should decide this themselves.

My personal preference would be for the guide to be visible in the menu, although the notice "work in progress" could stay. So maybe the flag should not be touched, but it should be ignored as far as loading items in the menu is concerned.

Please sign in to comment.