Comments (12)
I tried link-checker.
It works ok. See sample output below.
If we were to start with this I think we should limit it to README.md initially, as otherwise we have way too many broken links already :)
Link checker output file: link-checker/out.md
README.md
OK /meta/meetings.md
OK 30-day-warranty.md
OK CONTRIBUTING.md
OK bad-weather-for-liftoff.md
OK change-the-developers-mindset.md
OK common-requirements.md
OK contracted-contributor.md
OK crossteam-project-valuation.md
OK dedicated-community-leader.md
OK defeat-hierarchical-constraints.md
OK developer-incentive-alignment-for-innersource-contribution.md
OK gig-marketplace.md
OK http://bit.ly/innersource_patterns_videos
OK http://hillside.net/index.php/a-pattern-language-for-pattern-writing
OK http://innersourcecommons.org
...
OK start-as-experiment.md
ERROR http://creativecommons.org/licenses/by-sa/4.0/
(HTTP error 521)
ERROR i-am-not-here.md
Stat i-am-not-here.md: no such file or directory
from innersourcepatterns.
I tried a markdown linter on the README.md
file, just too see how that would look like.
If we don't check for line length (which the linter complaints about all over the place), we would still have these errors:
$ markdownlint README.md
README.md:1 MD041/first-line-heading/first-line-h1 First line in file should be a top level heading [Context: "This repository serves as the ..."]
README.md:3 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]
README.md:8 MD001/heading-increment/header-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h4]
README.md:59 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]
README.md:60:33 MD026/no-trailing-punctuation Trailing punctuation in heading [Punctuation: '?']
README.md:69:40 MD026/no-trailing-punctuation Trailing punctuation in heading [Punctuation: '?']
README.md:75 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]
README.md:76:20 MD026/no-trailing-punctuation Trailing punctuation in heading [Punctuation: '?']
README.md:84 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]
Would be interesting how we could arrive at a linter configuration that would be helpful, while not being a complete pain, especially for new contributors.
@maxcapraro have you worked with a markdown linter before? Any recommendations for a useful configuration?
from innersourcepatterns.
Spell check?
from innersourcepatterns.
Nice ideas. How does the output of "MD linter" look like? I have never seen one in action?
In addition a check for the require headilnes in pattern files would be nice. Basically a help for new authors to get the pattern format right. This is only really practicable once we have moved the patterns to a separate folder thought.
I think as a first step the 'dead link checker' would be most useful.
It's important that it can deal with relative links inside the markdown though (e.g. from README.md to a pattern file, as in the. case where we discovered this issue).
Two GitHub Actions that we could try:
- https://github.com/marketplace/actions/link-checker
- https://github.com/marketplace/actions/markdown-link-check
from innersourcepatterns.
Wow! Thanks for already looking into it :)
@maxcapraro have you worked with a markdown linter before? Any recommendations for a useful configuration?
Not really - I created the issue basically so that I don't forget to look into it :) Which - I think - I wouldn't be able to do in the next two weeks or so.
from innersourcepatterns.
If we were to start with this I think we should limit it to README.md initially, as otherwise we have way too many broken links already :)
Wow! We have quite many of these, indeed. So, maybe we start with the link checker instead of the linter?
from innersourcepatterns.
That looks great, thanks for trying out some marketplace actions already, because GitHub Actions would've exactly been my next suggestion. If you, or someone else, would want to to provide a pull request with a GitHub Actions starter for the repo I'd gladly review it and merge it :D 🎉
from innersourcepatterns.
Anybody feels strongly about the MD linting and wants to drive it?
My take is that any MD linter configuration will find way too many issues in the MD files that we have today. Instead we could write a custom "pattern .md file linter" that checks if the pattern files contain the right headlines (from the pattern template) or similar. That might be more useful for our purposes?
My take is to leave it at the link checker that we already added, and close this issue for the time being.
from innersourcepatterns.
Anybody feels strongly about the MD linting and wants to drive it?
My take is that any MD linter configuration will find way too many issues in the MD files that we have today.
The do indeed find quite a bit of stuff that might to be extensive for human oriented content. One can provide config to turn down the most noisy checks though.
Instead we could write a custom "pattern .md file linter" that checks if the pattern files contain the right headlines (from the pattern template) or similar. That might be more useful for our purposes?
Sounds like a good idea - And like something that could more or less work as shell script combining a bunch of grep & regexes. We'd need the rules to check for then. And provide some human readable content what is checked for (not everyone likes to read lovely monster regexes)
My take is to leave it at the link checker that we already added, and close this issue for the time being.
Would also be fine for me. What to @rrrutledge and @maxcapraro think?
from innersourcepatterns.
First of all: Wow! Discussion and first PR are great :)
I think (contrary to @lenucksi) that more sophisticated checks can be very very helpful. Like it does for code, automated checks allow us to focus on great semantic contents instead of syntactic issues. Though, I don't think I can commit to driving that forward within - say - the next month.
My take is to leave it at the link checker that we already added, and close this issue for the time being.
Our goal was to keep the repo (and issue tracker) as clean as possible for now - so no objection if you want to close the issue (for now ;-) )
from innersourcepatterns.
Ok. I vote for closing this then @maxcapraro in the spirit of clarity and focus in our repo :)
from innersourcepatterns.
Ok. I vote for closing this then @maxcapraro in the spirit of clarity and focus in our repo :)
Closing this for the time being then. Let's come back to this issues once the time is ready.
from innersourcepatterns.
Related Issues (20)
- Monthly Metrics: New Issues + New Pull Requests 2024-01-01..2024-01-31
- Monthly Metrics: Contributors 2024-01-01..2024-01-31
- Galician: Content Consistency Issue
- :brazil: Brazilian Portuguese: Content Consistency Issue
- :jp: Japanese: Content Consistency Issue
- :cn: Chinese: Content Consistency Issue
- Monthly Metrics: Contributors 2024-02-01..2024-02-29
- DRAFT - Standard Base Documentation: COMMUNICATION.md vs SUPPORT.md HOT 1
- Add RFC template repo to pattern
- bug: CODEOWNERS file has errors HOT 8
- [Pattern Draft] Maintainer Apprentice HOT 4
- :jp: Japanese: Content Consistency Issue
- :brazil: Brazilian Portuguese: Content Consistency Issue
- Galician: Content Consistency Issue
- :cn: Chinese: Content Consistency Issue
- Monthly Metrics: Contributors 2024-03-01..2024-03-31
- vale does not consider the configured exception list HOT 5
- :cn: Chinese: Content Consistency Issue
- :jp: Japanese: Content Consistency Issue
- Monthly Metrics: Contributors 2024-04-01..2024-04-30
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from innersourcepatterns.