cmu-lib / dhlg Goto Github PK

This draft design / layout seeks to address the needs of this page - a small approach to discovery / internal page navigation to aid uses with a long list of topics.
At the moment the design is for desktop screen only. The intent is to limit the size of the table of contents sidebar, allow it to float as needed with main page scroll.
This design requires approval / commentary.

@grunewas once #55 is finished, make a list of all content pages that are not yet finished, or not yet edited by me, that I need to go in and check or write.

Similar issues as Topics in DH page - Sidebar navigation proposed as internal page discovery solution.
Design approval / commentary requested. Design only functional for desktop at the moment.

Once there are anchor links available for topics (#35), @grunewas will need to go through the topics that cross reference each other and fix their links. For example, "Digital History" has a wide array of cross-ref links, all broken.

The latest updates have changed the way that one navigates to individual topic. Since the topic id is now an attribute of the enclosing div, it seems like there's no way to get a resolvable anchor link like /topics-in-dh#topic-hgis I believe we'll need this in place so that it's possible for us to link directly to a given topic at will from other pages on the site.

re #33

The design contains subfooter links - are there any?

Lunr.js is enabled, and indexes on build.

Should we index individual topics as internal links on the topics page? at the moment it builds only at the page level. 'HGIS' returns 'Topics in DH', however the search results does not make this evident, and links to the page itself, not the specific topic.

Please advise.

Thoughts @stop14?

https://www.youtube.com/channel/UCd3OL6bMTcGZBrjcfK7rIuw is still called "Carnegie Mellon University What Are DH" - should be renamed to CMU Digital Humanities Literacy Guidbook or some such

Do we have a sense of what kind of content this page will have? the current design imagines a header / splash image with three columns with teasers for other pages.

Are there sub pages?
Are block quotes needed?
What kinds of sections are involved?
Will there be any internal page navigation required?

Currently this page uses the page layout. If it requires a more involved layout, including a sidebar, we'll need to have a new layout

Given the nature of the site, is there any interest in retaining the built in changelog functionality of this theme? see /pages/changelog.md or in the build, /changelog/

I noted that there's a PDF in _projects (https://github.com/dSHARP-CMU/dh-literacy-web/blob/agile-development/_projects/DeDeoPracticalPrinciplesofData.pdf) @grunewas - is this intentional, and a file that we should be hosting on our site?

I've run in to a bunch of spelling typos across the different markdown files - pushed a few changes but they're too numerous for me to catch everything.

@grunewas if you open the markdown in even something like TextEdit on mac, or Notepad on Windows, it should underline and help out with spell check.

Our IA requests that pages have date metadata so we can specify when they were published. This isn’t yet present in the example page metadata, although it looks like _meta_information.html will display it once added - can you confirm that? (I might be looking in the wrong templates 😬 )

the Topics.md loop does not yet have an inner loop to provide links to Project pages assoc. with that topic. This is also in our IA requirements.

Right now, the project video "similar features by discipline" lumps all the videos matching all the source projects' disciplines into one list. This should isntead loop through each discipline, print the discipline name as a subhead, and then loop through displaying the other videos with that discipline.

Rather than filter by the wall of video thumbnails by Topic (since there are too many to make it useful), we suggest for a revised design that we filter by Discipline (@grunewas has provided a list of 15). That would help to mitigate the navigation of a giant wall of thumbnails. We could display the topic tags beneath the video thumbnails. According to @milnerm this is feasible.

As stated our info architecture, we want each project video page to have three lists of links:

1. List of project videos sharing the same Topics (e.g. in the sandbox, the with-video project and the single-page project share the topic Topic4 and so should display links to each other)
2. List of project videos sharing the same Disciplines (the sandbox project pages don’t share discipline tags, but if they did, we’d want them to link to each other)
3. Links to the proper Topic anchors on the Topics page (e.g. with-video should contain links that point to /topics#topic1 and /topics#topic4)

Right now, the Project template’s use of _meta_information.html doesn’t yet loop through its assigned disciplines/topics to link to related projects - instead it’s looping the topics/disciplines to display them as badges. Please update to match the IA requirements.

See, for example, "GlobalResourcesDh Community" - it is missing a ' > ' mark.

Also, I'm not certain how the link titles get generated, but they should probably be case sensitive, or else we need a way to force "DH Community" to have the 'H' capitalized.

Perhaps we can put this in the short description, or its own line?

related, to the extent we can remove the language.yml stuff, let’s – it looks quite vestigial, almost all of it applying to blog posts, which we don’t want in the site anyway.

I've revised the YAML Headers slightly for both topics and projects. Please consult the latest build. Either the md repository needs to be updated to reflect the new headers, or additional files should be added to this repository.

Important notes:

• title is the page title
• meta_title is the page head title
• remove: subheadline
• meta_teaser should be updated if there's interest in meta field descriptions etc. for SEO
• project md files should have teaser completed as it appears on the project landing page

Please edit authors for each md file and remove extraneous entries
all instances of identifier for disciplines, topics, and projects are case sensitive, and should be checked

Seeing the bios in action now, I'm thinking that going all caps simply makes them too hard to read. The caps works for the short category and name/affiliation lines, but I find it a bit grating on the longer text. @scottbot @stop14 thoughts?

nav menu pseudo element positioning requires debugging.

For example, Global Resources here links to https://global-resources/dh-community/ - is that an issue that will be resolved when this reaches a permanent home, or something that needs to be fixed now?

We probably only need to have two options in the attribution.yml file – not sure how you intend to wire that up yet since nothing in the templates references it so far.

Also, might be more understandable to name it "licensing" rather than "attribution"

The show_meta variable shouldn’t need to be set by the author. Only _projects and _topics need to render special links, and ALL pages (excluding index pages) should be showing date authored, author lists, and have the boolean flag for whether the content is “original” or “contributed” (I think Scott’s clarification email covered this already).

In general, if those kinds of flags can be implicit in either specifying the layout or the fact that a page belongs to e.g. the _projects collection and get handled by the _config.yml scoping rules, it should, so our authors don’t have to remember YAML metadata but just know that they can put the file into a folder and it’ll render fine.

Only the Project pages need links to video, so please revise the template logic and the example MD files so it’s clear that only those pages accept metadata with youtube links, and the others don’t need it.

I see in the example md files tags and categories YAML fields - these should be stripped out and templates modified to not use them, since they don't exist in our IA and our authors should not have to fill them out.

https://cmu-dh-literacy.netlify.com/topics-in-dh/

Seems to be attached to the ::before element right before h3??

Currently the project video pages use this metadata structure:

iframe: "<iframe width='970' height='546' src='//www.youtube.com/embed/r32qwAENWng' frameborder='0' allowfullscreen></iframe>"
#
# These video settings are totally optional. It's only purpose
# is SEO, so that videos show up in Google hopefully with a 
# thumbnail.
# More › https://developers.google.com/webmasters/videosearch/schema?hl=en&rd=1
#
# embedURL – A URL pointing to a player for the specific video.
# contentURL – A URL pointing to the actual video media file
# thumbnailUrl – A URL pointing to the video thumbnail image file.
#
video:
    embedURL: "https://www.youtube.com/embed/r32qwAENWng"
    contentURL: "http://www.youtube.com/watch?v=r32qwAENWng"
    thumbnailUrl: "http://img.youtube.com/vi/r32qwAENWng/0.jpg"

This makes the authors repeat a lot of info that should just be programmatically generated by entering the Youtube ID code (e.g. r32qwAENWng) exactly once in the yaml header.

The front page requires build

We do not need to track author metadata, so that file and all template dependencies should be removed. We only require pages to have a list of 1+ name+institution as free text in a given page’s YAML metadata, and those need to be displayed somewhere on the page, but not necessary to pull in any other metadata.

Example:

authors:
- "Susan Grunewald (University of Pittsburgh)"
- "Scott Weingart (Carnegie Mellon University)”

all the template needs to do is display those strings somewhere

The items in the main navigation menu could be shorter in length. The current character lengths result in a very wide menu that causes layout issues with screens below 1366px. Essentially with the current lengths we need smaller fonts so the items don't feel cramped.

If a pipe character needs to be escaped when using markdownify, it causes an error. Without escaping a pipe results in a table layout as per markdown.
This currently occurs in Lavin.md
This might be a bug related to the version of Kramdown (~>1.14) in Jekyll 3.8.5. It's supposedly fixed in 1.16. Other dependencies in the gemfile.lock use Kramdown 1.17.

This may be related: gettalong/kramdown#477

Do we have a series of stock header / splash images which are appropriate or desirable to use for What are DH? and in some other contexts in the site?

Instead of repeating "Posted by..." for each author

The main text appearing in the footer is the site description. Is this accurate?

So, with feedback from @scottbot and after consultation with @milnerm and @stop14, we're going to produce a one-page solution for the Topics in DH page. We'll strip out the filter and list the topics in columns, as in the existing design. Each topic will be viewable in a modal window.

The alternatives would be old-school UIs, with a long single page: either a jump-down from the topic list to topic entries, or a long accordion view. We think the modal view is the most elegant of the UI choices available.

Could the video projects browse page be tightened up a bit by getting rid of the "play video" button (which doesn't even play the video, but instead takes you to a dedicated page.) Turn the video thumbnails and titles into links perhaps?

The current solution generates topic page anchor links based on an integer counter. Topics anchor links should be human-readable, generated based on the .md filename if possible, or some other human-readable slug, so that it’s easy for authors to add links to specific topics when authoring markdown (for example, in a paragraph at /topics#networks I may want to include a link to /topics#gis, rather than needing to write /topics#topic2 or the like).

The footer contains a place for links, should this be retained? if so, please update _data/footerlinks.yml
If not, shall we remove the functionality entirely, and relayout the columns in the footer?

@mdlincoln @grunewas -- @milnerm still needs the Disciplines.json control list to make everything build out correctly.

Current Youtube thumbnails are 4:3 (480x360), resulting in top and bottom black bands. Revise them to 16:9?

@milnerm not an issue per se, but I've been wanting to set up a netlify CI so that it's easier for our project team to see a preview of the site as it develops. I've added a _netlify_config.yml file that only gets called by netlify during the build. I've also modified the Gemfile.lock - for unclear reasons 😬 Netlify doesn't seem to like Bundler >=2.0 explicitly called out in the file, so I've removed the final lines of the lock file describing the bundler version used for it. This doesn't seem to cause problems on the local build, and it allows the netlify build to go forward.

All this means is, please don't go regenerating Gemfile.lock without being sure to keep those final lines off (unless you have more experience with Netlify on fixing this issue - I've never run in to it before with them, but I'm also not interested in spending more time trying to debug it now that we've got a fix in place)

If this sounds fine, we can close out this note.

The Gemfile is locked currently pointed to ‘jekyll’, rather than the ‘gh-pages’. We’d like this to build on gh-pages eventually, so please lock to that gem instead of to the most current Jekyll (as described in https://github.com/github/pages-gem#conventional), just to make entirely sure that we aren’t accidentally trying to use any plugins that aren’t whitelisted by GitHub. Let me know ASAP if this is going to be a problem, because it directly impacts how we plan to deploy the site in production.

Disciplines Control is now carried out by a yml file rather than json to allow for consistent case-sensitive identifiers across topics and disciplines. Entries now consist of identifier and name fields.